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.
© 1994-2008 ARC™ International. All rights reserved.
© Freescale Semiconductor, Inc. 2010 - 2012. All rights reserved.
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.
© Freescale Semiconductor, Inc., 2010, 2011. All rights reserved.
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 ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
13
-
14
-
15
-
16
-
17
-
18
-
19
-
20
-
21
-
22
-
23
-
24
-
25
-
26
-
27
-
28
-
29
-
30
-
31
-
32
-
33
-
34
-
35
-
36
-
37
-
38
-
39
-
40
-
41
-
42
-
43
-
44
