NXP S08JS Reference guide

Freescale Medical Connectivity Library

API Reference Manual

Document Number: MEDCONLIBAPIRM

Rev. 4

05/2012

How to Reach Us:

Home Page:

www.freescale.com

E-mail:

suppor[email protected]

USA/Europe or Locations Not Listed:

Freescale Semiconductor

Technical Information Center, CH370

1300 N. Alma School Road

Chandler, Arizona 85224

+1-800-521-6274 or +1-480-768-2130

suppor[email protected]

Europe, Middle East, and Africa:

Freescale Halbleiter Deutschland GmbH

Technical Information Center

Schatzbogen 7

81829 Muenchen, Germany

+44 1296 380 456 (English)

+46 8 52200080 (English)

+49 89 92103 559 (German)

+33 1 69 35 48 48 (French)

suppor[email protected]

Japan:

Freescale Semiconductor Japan Ltd.

Headquarters

ARCO Tower 15F

1-8-1, Shimo-Meguro, Meguro-ku,

Tokyo 153-0064, Japan

0120 191014 or +81 3 5437 9125

suppor[email protected]

Asia/Pacific:

Freescale Semiconductor China Ltd.

Exchange Building 23F

No. 118 Jianguo Road

Chaoyang District

Beijing 100022

China

+86 10 5879 8000

suppor[email protected]

For Literature Requests Only:

Freescale Semiconductor Literature Distribution Center

1-800-441-2447 or 303-675-2140

Fax: 303-675-2150

LDCForFreescaleSemiconductor@hibbertgroup.com

Information in this document is provided solely to enable system and

software implementers to use Freescale Semiconductor products. There are

no express or implied copyright licenses granted hereunder to design or

fabricate any integrated circuits or integrated circuits based on the

information in this document.

Freescale Semiconductor reserves the right to make changes without further

notice to any products herein. Freescale Semiconductor makes no warranty,

representation or guarantee regarding the suitability of its products for any

particular purpose, nor does Freescale Semiconductor assume any liability

arising out of the application or use of any product or circuit, and specifically

disclaims any and all liability, including without limitation consequential or

incidental damages. “Typical” parameters that may be provided in Freescale

Semiconductor data sheets and/or specifications can and do vary in different

applications and actual performance may vary over time. All operating

parameters, including “Typicals”, must be validated for each customer

application by customer’s technical experts. Freescale Semiconductor does

not convey any license under its patent rights nor the rights of others.

Freescale Semiconductor products are not designed, intended, or authorized

for use as components in systems intended for surgical implant into the body,

or other applications intended to support or sustain life, or for any other

application in which the failure of the Freescale Semiconductor product could

create a situation where personal injury or death may occur. Should Buyer

purchase or use Freescale Semiconductor products for any such unintended

or unauthorized application, Buyer shall indemnify and hold Freescale

Semiconductor and its officers, employees, subsidiaries, affiliates, and

distributors harmless against all claims, costs, damages, and expenses, and

reasonable attorney fees arising out of, directly or indirectly, any claim of

personal injury or death associated with such unintended or unauthorized

use, even if such claim alleges that Freescale Semiconductor was negligent

regarding the design

Freescale™ and the

Freescale logo are trademarks of Freescale Semiconductor, Inc. All other

product or service names are the property of their respective owners.

Document Number: MEDCONLIBAPIRM

Rev. 4

05/2012

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor iii

Revision History

To provide the most up-to-date information, the revision of our documents on the World Wide Web will be

the most current. Your printed copy may be an earlier revision. To verify you have the latest information

available, refer to:

http://www.freescale.com

The following revision history table summarizes changes contained in this document.

Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc.

Revision

Number

Revision

Date

Description of Changes

Rev. 1 10/2009 Initial release.

Rev. 2 07/2010 Updated Reference Material section.

Rev. 3 07/2011 Minor editorial changes

Rev. 4 05/2012 Added new chapter IEEE 11073 Manager

MEDCONLIB API Reference Manual, Rev. 4

v Freescale Semiconductor

Chapter 1

Before Beginning

1.1 About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.2 Reference Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.3 Acronyms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

1.4 Function Listing Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Chapter 2

Medical Connectivity Library API Overview

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.2 API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.3 Using API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

2.3.1 Using the Medical Connectivity Library API . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

2.3.1.1 Initialization Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Chapter 3

Transport Layer API

3.1 Transport Layer API Function Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1.1 TIL_Initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Chapter 4

Medical Connectivity Library API

4.1 Medical Connectivity Library API Function Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

4.1.1 Ieee11073Initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

4.1.3 AgentSendAssociationReleaseRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Chapter 5

Data Structures

5.1 Data Structure Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1.1 MED_APP_CALLBACK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1.2 PPMSEGDATAXFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1.4 PCLRPMSEGMINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

5.1.8 PTR_TIL_RX_BUFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

5.1.10 PFN_SHIM_INITIALIZE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

5.1.11 PFN_SHIM_DEINITIALIZE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

5.1.13 PFN_SHIM_RECV_DATA() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

5.1.15 PSHIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

5.1.16 PTIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Chapter 6

PHDC Host Class API

6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor vi

6.3 PHDC Host Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.3.1 PHDC specific status codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.3.2 PHDC control request types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

6.4 PHDC data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

6.5 PHDC function listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

6.5.1 usb_class_phdc_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

6.5.2 usb_class_phdc_set_callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

6.5.3 usb_class_phdc_send_control_request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5

6.5.4 usb_class_phdc_recv_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7

6.5.5 usb_class_phdc_send_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 1-1

Chapter 1

Before Beginning

1.1 About This Book

This book describes the Freescale Medical Connectivity Library API functions. It describes in detail the

API functions that can be used by application code to develop various Medical device specializations.

Table 1-1 shows the summary of chapters included in this book.

Table 1-1. MEDCONLIBAPIRM Summary

1.2 Reference Material

Use this book in conjunction with:

• Freescale USB Stack with PHDC Device Users Guide (document USBUG)

• Freescale USB Stack with PHDC API Reference Manual (document USBAPIRM)

• Medical Connectivity Library Users Guide (document MEDCONLIBUG)

• IEEE Std 11073-20601TM-2008, Health informatics — Personal health device

communication-Part 20601: Application profile — Optimized Exchange Protocol.

Chapter Title Description

Before Beginning This chapter provides the prerequisites of reading this book.

Medical Connectivity Library

API Overview

This chapter gives an overview of the API functions and how to use them for developing

new medical device specialization applications.

Transport Layer API This chapter discusses Transport Layer API interfaces.

Medical Connectivity Library

API

This chapter discusses Medical Connectivity Library API interfaces.

Data Structures This chapter discusses the various data structures used in the USB device class layer API

functions.

Before Beginning

MEDCONLIB API Reference Manual, Rev. 4

1-2 Freescale Semiconductor

1.3 Acronyms and Abbreviations

CFV1 ColdFire V1 (MCF51JM128 CFV1 device is used in this document)

CFV2 ColdFire V2 (MCF52221 and MCF52259 CFV2 devices are used in this

document)

DIM Domain Information Model

IDE Integrated Development Environment

ISO International Organization for Standardization

IEEE The Institute of Electrical and Electronics Engineers

JM60 MC9S08JM60 Device

PHD Personal Healthcare Device

PHDC Personal Healthcare Device Class

TIL Transport Independent Layer

USB Universal Serial Bus

Before Beginning

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 1-3

1.4 Function Listing Format

This is the general format of an entry for a function, compiler intrinsic, or macro.

function_name()

A short description of what function function_name() does.

Synopsis

Provides a prototype for function function_name().

<return_type> function_name(

<type_1> parameter_1,

<type_2> parameter_2,

...

<type_n> parameter_n)

Parameters

parameter_1 [in] — Pointer to x

parameter_2 [out] — Handle for y

parameter_n [in/out] — Pointer to z

Parameter passing is categorized as follows:

• In — Means the function uses one or more values in the parameter you give it without storing any

changes.

• Out — Means the function saves one or more values in the parameter you give it. You can examine

the saved values to find out useful information about your application.

• In/out — Means the function changes one or more values in the parameter you give it and saves

the result. You can examine the saved values to find out useful information about your application.

Description

Describes the function function_name(). This section also describes any special characteristics or

restrictions that might apply:

• function blocks or might block under certain conditions

• function must be started as a task

• function creates a task

• function has pre-conditions that might not be obvious

• function has restrictions or special behavior

Return Value

Specifies any value or values returned by function function_name().

See Also

Lists other functions or data types related to function function_name().

Before Beginning

MEDCONLIB API Reference Manual, Rev. 4

1-4 Freescale Semiconductor

Example

Provides an example (or a reference to an example) that illustrates the use of function function_name().

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 2-1

Chapter 2

Medical Connectivity Library API Overview

2.1 Introduction

The Freescale Medical Connectivity Library API consists of the functions that can be used at the

application level. These enable you to implement different medical specializations.

2.2 API Overview

This section describes the list of API functions and their use.

Table 2-1 summarizes the Transport Layer API functions.

Table 2-2 summarizes the Medical Connectivity Library API functions.

Table 2-1. Summary of Transport Layer API Functions

No. API Function Description

1 TIL_Initialize() Initializes Transport Independent Layer

2 TIL_DeInitialize() De-initializes Transport Independent Layer

3 TIL_StartTransport() Initializes Shim

4 TIL_StopTransport() De-Initializes Shim

5 TIL_SendAPDU() Sends data through Shim

6 TIL_RecvApdu() Receives data from Shim

Table 2-2. Summary of Medical Connectivity Library API Functions

No. API Function Description

1 Ieee11073Initialize() Initializes Medical Connectivity Library

2 AgentSendAssociationRequest() Sends Association request packet to the Manager

3 AgentSendAssociationReleaseRequest() Sends Association release request to the Manager

4 AgentSendMeasurements() Sends single person measurements

5 AgentSendPersonMeasurements() Sends multi person measurements

6 AddEntryToObsScanList() Adds an entry to the Observation Scan list

7 AddEntryToScanRptPerVarList() Adds an entry to the Scan report per var list

8 UpdatePmSegmentEntry() Updates PM Segment entry data

9 SendSegmentData() Sends PM Segment data event to the manager

Medical Connectivity Library API Overview

MEDCONLIB API Reference Manual, Rev. 4

2-2 Freescale Semiconductor

2.3 Using API

This section describes the flow on how to use various Medical Connectivity Library API functions.

2.3.1 Using the Medical Connectivity Library API

This section describes a sequence to use the Medical Connectivity Library API functions from the

application.

2.3.1.1 Initialization Flow

To initialize the driver layer, the class driver must:

1. Call 3.1.1"TIL_Initialize()" to initialize the Transport Independent Layer.

2. Call 3.1.2"Ieee11073Initialize()" to initialize the Medical Connectivity Library and to start

transport.

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 3-1

Chapter 3

Transport Layer API

This section discusses the Transport Layer API functions in detail.

3.1 Transport Layer API Function Listings

3.1.1 TIL_Initialize()

Initializes the Transport Independent Layer (TIL).

Synopsis

void TIL_Initialize(PTIL pTil))

Parameters

pTil [in] — Pointer to TIL

Description

This function initializes TIL with the input pointer.

Return Value

None

Transport Layer API

MEDCONLIB API Reference Manual, Rev. 4

3-2 Freescale Semiconductor

3.1.2 TIL_DeInitialize()

De-Initializes the Transport Independent Layer.

Synopsis

void TIL_DeInitialize(void)

Parameters

None

Description

This function de-initializes TIL (that is, sets TIL pointer to NULL).

Return Value

None

Transport Layer API

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 3-3

3.1.3 TIL_StartTransport()

Initializes the Shim Layer.

Synopsis

PSHIM TIL_StartTransport(

PTIL

pTil,

eShimID

ShimID,

APP_CALLBACK

pAppCallback)

Parameters

pTil [in] — Pointer to TIL

ShimID [in] — Shim Id

pAppCallback [in] — Application callback function

Description

This function initializes the Shim identified by the Shim Id and registers the application callback function.

Return Value

• Shim pointer if success

• NULL if unsuccessful

Note:

This API is used within the library, so the application should avoid using this API.

Transport Layer API

MEDCONLIB API Reference Manual, Rev. 4

3-4 Freescale Semiconductor

3.1.4 TIL_StopTransport()

De-Initializes the Shim Layer.

Synopsis

ERR_CODE TIL_StopTransport(

PTIL

pTil,

eShimID

ShimID)

Parameters

pTil [in] — Pointer to TIL

ShimID [in] — Shim Id

Description

This function de-initializes the Shim identified by the Shim Id.

Return Value

• ERROR_SUCCESS (success)

• ERR_UNINITIALIZED_SHIM (shim already uninitialized)

Note:

This API is used within the library, so the application should avoid using this API.

Transport Layer API

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 3-5

3.1.5 TIL_SendAPDU()

Sends data through the Shim.

Synopsis

ERR_CODE TIL_SendAPDU(

PTIL

pTil,

eShimID

ShimID,

boolean

metadata,

uint_8

num_tfr,

uint_8

current_qos,

PTR_BUFFSTACK

pBuffStack)

Parameters

pTil [in] — Pointer to TIL

ShimID [in] — Shim Id

metadata [in] — Metadata flag

num_tfr [in] — Number of transfers

current_qos [in] — Data quality of service

pBuffStack [in] — Pointer to the send buffer

Description

This function identifies the Shim by the Shim id and sends data through Shim using the input parameters.

Return Value

• ERROR_SUCCESS (success)

• ERR_UNINITIALIZED_SHIM (shim uninitialized)

• ERR_SEND_FAILED (failed to send data)

Note:

This API is used within the library, so the application should avoid using this API.

Transport Layer API

MEDCONLIB API Reference Manual, Rev. 4

3-6 Freescale Semiconductor

3.1.6 TIL_RecvApdu()

Receives data from the Shim.

Synopsis

ERR_CODE TIL_RecvApdu(

PTIL

pTil,

eShimID

ShimID,

uint_8

current_qos,

PTR_BUFFSTACK

pBuffStack)

Parameters

pTil [in] — Pointer to TIL

ShimID [in] — Shim Id

current_qos [in] — Data quality of service

pBuffStack [in] — Pointer to the receive buffer

Description

This function identifies the Shim by the Shim Id and receives data from the Shim using the input

parameters.

Return Value

• ERROR_SUCCESS (success)

• ERR_UNINITIALIZED_SHIM (shim uninitialized)

• ERR_RECV_FAILED (failed to receive data)

Note:

This API is used within the library, so the application should avoid using this API.

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 4-1

Chapter 4

Medical Connectivity Library API

This section discusses the Medical Connectivity Library API functions in detail.

4.1 Medical Connectivity Library API Function Listings

4.1.1 Ieee11073Initialize()

Initializes the Medical Connectivity Library.

Synopsis

ERR_CODE Ieee11073Initialize(

PTIL

pTil,

eShimID

ShimID,

MED_APP_CALLBACK

pfnAppCallback)

Parameters

pTil [in] — Pointer to TIL

ShimID [in] — Pointer to Shim

pfnAppCallback [in] — Application callback pointer

Description

This function initializes the Medical Connectivity Library, starts the transport identified by the Shim

pointer and registers a callback function to the application.

Return Value

• ERROR_SUCCESS (success)

• ERR_GENERAL (start transport failed)

Medical Connectivity Library API

MEDCONLIB API Reference Manual, Rev. 4

4-2 Freescale Semiconductor

4.1.2 AgentSendAssociationRequest()

Sends association request packet to the Shim Layer.

Synopsis

ERR_CODE AgentSendAssociationRequest(DataProtoList* pDataProtoList)

Parameters

pDataProtoList [in] —Pointer to the data proto list

Description

This function adds the association request packet header to the data proto list and sends the association

request packet to the Shim Layer to be transported to the manager.

Return Value

• ERROR_SUCCESS (success)

• ERR_INVALID_REQUEST (device not in a state to send association request)

• ERR_INSUFFICIENT_MEMORY (if unable to add header)

4.1.3 AgentSendAssociationReleaseRequest()

Sends association release request packet to the Shim Layer.

Synopsis

ERR_CODE AgentSendAssociationReleaseRequest(Release_request_reason RelReqRes)

Parameters

RelReqRes [in] — Reason for releasing association

Description

This function adds the association release request packet header to the release request reason and sends the

association release request packet to the Shim Layer to be transported to the manager.

Return Value

• ERROR_SUCCESS (success)

• ERR_INVALID_REQUEST (device not in a state to send association release request)

• ERR_INSUFFICIENT_MEMORY (if unable to add header)

Medical Connectivity Library API

MEDCONLIB API Reference Manual, Rev. 4

Freescale Semiconductor 4-3

4.1.4 AgentSendMeasurements()

Sends measurements taken by the application to the manager.

Synopsis

ERR_CODE AgentSendMeasurements(

ObservationScanList* (*

pObsScanList)[],

HANDLE

handle,

intu8

ReportType,

intu16

ScanCount,

intu8

bConfirm)

Parameters

pObsScanList [in] — Pointer to an array of observation scan lists

handle [in] —Handle of the object which has to send measurements

ReportType [in] — Type of report

ScanCount [in] —Number of scans

bConfirm [in] — True for confirmed event report

Description

This function validates and sends the measurements given by the observation scan list array via the object

specified by the handle in the format given by the report type. This API is used to send measurements when

the device does not have support for multi persons.

Return Value

• ERROR_SUCCESS (success)

• ERROR_INVALID_PARAM (input parameters incorrect)

• ERROR_INVALID_DATA (data in observation Scan list is incorrect)

• ERR_INSUFFICIENT_MEMORY (memory constraint)

Page is loading ...

NXP S08JS Reference guide

This manual is also suitable for

NXP S08JS Reference guide

Related papers

Other documents