Concept2

PRELIMINARY

Performance Monitor Generation III (PM3) and Performance Monitor Generation IV (PM4) Communications Interface Definition

Filename: Concept2 PM Communication Interface Definition 014.doc

Revision: 0.14

4/1/2008 2:42 PM

Concept2

Morrisville, VT 05661

802-888-5226 (Voice)

802-888-6331 (Fax)

rowing@concept2.com
Table of Contents

List of Figures.. 5

List of Tables.. 5

Purpose and Scope. 7

Document History.. 7

Related Documents. 7

Note to Developers.. 8

Overview... 8

Data Flow... 8

Protocol Framework.. 18

Frame Structure. 18

Frame Contents. 19

Command Format 19

Response Format 20

PM3 Manufacturer Information.. 20

PM3 Extensions. 21

Protocol Layer Definition.. 21

Universal Serial Bus. 21

Physical Layer 21

Data Link Layer 22

Network and Transport Layers. 24

Protocol Features.. 25

CSAFE Default Configuration.. 25

CSAFE State Machine Operation.. 26

CSAFE Unsupported Features. 27

Command and Response Definitions.. 27

Workouts. 27

Configuring a Programmed Workout 27

Programmed Workout Parameter Limits. 28

PC-Host Dynamic Link Library (DLL) and Application Programming Interface (API) 28

Overview... 28

Architecture. 29

PM3/PM4 Device Discovery & Interface. 29

Media Interfaces. 29

USB Interface. 29

802.xx Interface (RF network) 29

Asynchronous Interface (RS232/485) 29

ANT Interface (RF network) 29

CSAFE+ Command Interface. 29

User Application API 31

PM3/PM4 Device Discovery & Interface API 31

Data Type Definitions. 31

Function Reference. 31

CSAFE Interface API 39

PM3 USB Interface API 43

Example Application Logic – CSAFE DLLs. 48

Example Application Logic – USB DLL (“direct interface”). 49

Appendix A.. 49

CSAFE Commands Implemented.. 50

Short Commands. 50

Long Commands. 52

CSAFE PM3-Specific Commands Implemented.. 54

Short Commands. 54

Long Commands. 55

Appendix B.. 56

PM3 Data Conversions. 56

Watts <-> Pace. 56

Calories/Hr <-> Pace. 56

Pace <-> /500m Pace. 56

Appendix C.. 56

Standard List Workouts. 56

Custom List Workouts. 56

Appendix D.. 57

PM3/PM4 Error Codes. 57

Appendix E. 70

PMSDKDemo Application.. 70

Command Example #1 – Get Horizontal Command. 70

Command Example #2 – Get PM3Worktime and Get PM3Workdistance Command. 72

Command Example #3 – Set Programmed Workout Command. 75

Appendix F. 78

PM4 Status LED State Definitions. 78

List of Figures

 

Figure 1 - Standard Frame Format.. 18

Figure 2 - Extended Frame Format.. 18

Figure 3 - Long Command Format.. 19

Figure 4 - Short Command Format.. 20

Figure 5 - Response Frame Contents Format.. 20

Figure 6 - Individual Command Response Format.. 20

Figure 7 - CSAFE State Machine Diagram.. 26

Figure 8 – Demo Application Screen Shot – CSAFE Get Horizontal Command.. 72

Figure 9 – Demo Application Screen Shot – Get PMWorkTime & Get PMWorkDistance. 74

Figure 10 – Demo Application Screen Shot – Set Programmed Workout.. 77

List of Tables

 

Table 1 - Document Modification History...................................................................................................... 7

Table 2 - Related Documents................................................................................................................................ 7

Table 3 - PM3/PM4 Configuration/Data to PC................................................................................................ 9

Table 4 - PC Configuration/Data to PM3....................................................................................................... 15

Table 5 - Extended Frame Addressing.............................................................................................................. 18

Table 6 - Unique Frame Flags............................................................................................................................... 19

Table 7 - Byte Stuffing Values........................................................................................................................... 19

Table 8 - Command Field Types........................................................................................................................... 20

Table 9 - Response Field Types............................................................................................................................. 20

Table 10 - CSAFE Concept2 PM3/PM4 Information...................................................................................... 20

Table 11 - PM-Specific CSAFE Command Wrappers...................................................................................... 21

Table 12 - PM Proprietary CSAFE Command Wrappers............................................................................ 21

Table 13 - USB Series B Receptacle Mechanical......................................................................................... 21

Table 14 - USB Series B Receptacle Connector Pin-out........................................................................... 22

Table 15 - PM3/PM4 USB Definitions.................................................................................................................. 24

Table 16 - PM3 CSAFE Protocol Defaults...................................................................................................... 25

Table 17 - PM3 Unsupported CSAFE Protocol Features.......................................................................... 27

Table 18 - Workout Configuration Parameter Limits............................................................................. 28

Table 19 - PM3/PM4 Error Code Descriptions................................................................................................ 57

Table 20 - Status LED State Definitions........................................................................................................ 78

Purpose and Scope

 

This document contains the communications interface definition for the Concept2 PM3 and PM4.   The PM3/PM4 is the performance monitor for the indoor rower providing the ability to communicate with a host PC utilizing Universal Serial Bus (USB) media.

Feedback on this document and the SDK itself should be provided via the protected forum (http://concept2.ipbhost.com) for software developers.  Your protected forum password should have already been provided to you.  If not, please contact Scott Hamilton (rowing@concept2.com) at Concept2.

Document History

 

Table 1 - Document Modification History

Related Documents

 

Table 2 - Related Documents

Note to Developers

 

This document provides sufficient information to allow a software developer to create custom PC applications for the PM3/PM4, using the provided Data Link Libraries (DLLs).  This document assumes the developer has experience writing applications that interface to DLLs.

Another option available to developers is a software tool called Performance Monitor Interface or PMI, written by Chris Brett.  The PMI is aimed at simplying the task of developing applications that are capable of processing data from the PM3/PM4.  The free software and documentation is available for download here:

http://www.concept2.co.uk/software/pmi.php

Overview

 

The PM3/PM4 communication protocol is intended for use over the Universal Serial Bus (USB).  The PM3/PM4 protocol is based on the CSAFE protocol that is targeted at supporting communications between physical fitness equipment and a host PC.  Extensions to the CSAFE protocol are employed to provide the PM-specific functionality not supported by the generic protocol while maintaining compatibility. 

The communication protocol possesses the following basic features:

·         Self-starting frame structure with data transparency over numerous physical interfaces

·         Simple state machine model for master/slave interactions

·         “Speak-when-spoken-to” configuration with the option for well-defined unsolicited response communication

·         Point-to-point and point-to-multi-point network configurations

·         Error detection

·         Standardized data formats for time, distance, etc.

·         Extensibility by virtue of equipment vendor identification and vendor custom command definitions

The following sections provide the communication protocol definition including the physical, data link, network, and transport layer aspects for each interface.

Data Flow

 

The following sections summarize the data used by a host PC for controlling, configuring, and monitoring a single PM3/PM4.  The data flow is separated into data originating from the PM3/PM4 or from the host PC.  The various data along with the size and update rate requirement serve to establish the commands/responses that exist within the communication protocol.  Certain data may be included in more than one command/response if dictated by the data flow requirements.

Table 3 - PM3/PM4 Configuration/Data to PC

Notes:

1.        At 2000 rpm of flywheel (2000 rpm/60 seconds/m x 3 tics/revolution x 1/12.93 tics/meter = 7.7 meters/second)

2.        At 100 strokes/min

3.        Dependent on configuration

4.        Hours/Minutes/Seconds in byte format

5.        Dependent on capability code

Table 4 - PC Configuration/Data to PM3

Notes:

1.        Hours/Minutes/Seconds in byte format

2.        Year/Month/Day in byte format

3.        “Programmed” workout takes either workout time or horizontal distance goals to set-up a “fixed time” or “fixed distance” workout; “Favorites #1 – 5” are only available if a logcard is present. “Standard List” workouts defined in Standard List Workouts.

4.        Default screen error display mode is enabled and will return to enabled upon each power-up.  In the disabled mode, no error information will be displayed on the PM3/PM4 screen, but will be available through the command interface.  All errors will be latched and cleared only by reading the error value via the command interface when the screen error display mode is disabled.

Protocol Framework

 

In the CSAFE protocol, communication between the master and the slave(s) device is accomplished using two basic frame types: standard frame and extended frame.  The standard frame provides no provisions for slave-to-slave communication or multi-drop network configurations, as device addressing is implicit.  The PM3/PM4 application requires explicit device addressing for numerous scenarios (as provided by the extended frame format) so that both frame types will be handled for our implementation.  In general, the slave device only speaks when responding to a master’s request.  Certain exceptions may be made in very specific circumstances.

The extended frame is defined as stream of bytes with the structure shown in Figure 2.  Note that the standard and extended frames are identical with the exception of the frame-unique start flag and the device address information.  The start flags and stop flag are unique values used to delineate the frame and, therefore, cannot appear in the frame contents or the checksum.  A byte-stuffing technique is employed to ensure that these unique bytes do not occur elsewhere in the frame.  A checksum is included in the frame to allow both the master and slave devices to verify the integrity of the “Frame Contents”.  Neither an acknowledgement (ACK) nor negative acknowledgement (NAK) at the frame level is an integral part of the protocol.

Figure 1 - Standard Frame Format

Figure 2 - Extended Frame Format

Frame Structure

 

The frame structure is a stream of bytes with a unique start byte, optional addressing, frame contents (e.g., commands and responses), a checksum and a unique stop byte.  The unique start and stop byte values are shown in Table 6.  In order to ensure that these start and stop values do not appear anywhere in the frame, the master and slave devices perform “byte-stuffing” and “byte-unstuffing” on the byte stream (i.e., frame contents including extended frame addresses and checksum).  This technique can be performed “on the fly” without impacting the data stream buffering requirements since the extra bytes only exist on the data link.

The extended frame addressing rules are summarized in Table 5.

Table 5 - Extended Frame Addressing

The “byte-stuffing” algorithm simply substitutes two bytes for each of the unique bytes listed in Table 6.  The unique Byte Stuffing Flag is followed by a 0x00, 0x01, 0x02, or 0x03 as shown in Table 7 depending on the byte being replaced.  The impact of this technique on the data link is that the frame size could increase in size by a factor of two in the worst case.

Table 6 - Unique Frame Flags

Table 7 - Byte Stuffing Values

The frame beginning and end are designated by the unique Start and Stop bytes.  If a Start or Stop byte is missed, the frame is discarded and frame resynchronization occurs at the beginning of the next frame.  Once a full frame is received and all “byte-unstuffing” is performed, a one-byte checksum is computed with byte-by-byte XORing of the frame contents to verify frame integrity.  The frame definition does not explicitly place any limits on the frame length.  Because the entire frame contents must be buffered before computing the checksum, memory resources on the slave devices typically establish the restrictions on frame length.  For CSAFE protocol compatibility, the following frame length restrictions are invoked for the PM3/PM4 USB physical link:

1.        A maximum frame size of 96 bytes including start/stop flags, checksum and byte stuffing

2.        All flow control handled natively as part of USB

Frame Contents

 

The frame protocol transports frame content data consisting of both commands and responses.  The only restrictions on the frame contents relate to length of frame and the requirement that individual commands/ responses do not straddle a frame boundary (i.e., no partial commands/responses within a frame).  The following sections detail the command and response formats.

Command Format

 

All commands have one of two basic formats: long command or short command.  Long commands are those including command data while short commands are command only.  The command is represented by a single byte with the command address space partitioned equally (i.e., long commands have MS bit clear and short commands have MS bit set).  Figure 3 and Figure 4 illustrate the long and short command formats, respectively.

Figure 3 - Long Command Format

Figure 4 - Short Command Format

In the long command format, the Long Command and Data Byte Count fields are single bytes.  The Data Byte Count field determines the Data field size.  The short command format consists solely of the single byte Short Command.  Table 8 summarizes the command field types for both the long and short commands.  Note that the command formats allows a long command with a Data Byte Count of 0 and no bytes in the Data field.  The virtue of the Data Byte Count field in the long command is to allow slave devices to handle unrecognized commands by merely disregarding the command and its data while continuing to process succeeding commands within the same frame. 

Table 8 - Command Field Types

Multiple complete commands can be included in a single frame, but no partial commands or responses are allowed.  Sending a frame consisting of multiple commands to a slave device results in a frame consisting of multiple command responses being generated by a slave.

Response Format

 

All responses have the same Frame Contents format as shown in Figure 5. 

Figure 5 - Response Frame Contents Format

Figure 6 - Individual Command Response Format

Table 9 - Response Field Types

PM3 Manufacturer Information

 

Table 10 summarizes the Concept2 PM3/PM4 product-specific information.

Table 10 - CSAFE Concept2 PM3/PM4 Information

PM3 Extensions

 

The PM3/PM4 extensions to the frame protocol involve utilizing one pre-defined custom command that serves as a “wrapper” for additional PM-specific commands.  The one command is defined in Table 11.  The one custom command wrapper is used to expand the CSAFE command set for additional configuration and data operations. See Appendix A for a detailed explanation of the command wrapper implementation.

Table 11 - PM-Specific CSAFE Command Wrappers

Additional PM3/PM4 proprietary extensions to the frame protocol involve utilizing four commands added to the existing CSAFE protocol command set that serve as “wrappers” for the PM3/PM4 command set.  The four commands are defined in Table 12.  The four command wrappers are used to partition the PM3/PM4 command set space into “push” (i.e., set) and “pull” (i.e., get) operations for configuration and data.  The use of these command wrappers allow the PM3/PM4 to support existing CSAFE protocol commands while introducing PM3/PM4 proprietary commands only accessible via the command set extension. These commands are not accessible via the “public” interface and require special “authentication” with the PM3/PM4 to function.

Table 12 - PM Proprietary CSAFE Command Wrappers

Protocol Layer Definition

 

Universal Serial Bus

 

Physical Layer

 

USB Version 1.10 operating at full speed (12 Mb/s).

Table 13 - USB Series B Receptacle Mechanical

Table 14 - USB Series B Receptacle Connector Pin-out

Data Link Layer

 

In general, USB transactions consist of

3.        Token Packet (Header defining what it expects to follow), an

4.        Optional Data Packet, (Containing the payload) and a

5.        Status Packet (Used to acknowledge transactions and to provide a means of error correction)

USB is a host centric bus. The host initiates all transactions. The first packet, also called a token is generated by the host to describe what is to follow and whether the data transaction will be a read or write and what the device’s address and designated endpoint is. The next packet is generally a data packet carrying the payload and is followed by a handshaking packet, reporting if the data or token was received successfully, or if the endpoint is stalled or not available to accept data.

Data on the bus is transmitted LS bit first. USB packets consist of the following fields,

Sync

All packets must start with a sync field. The sync field is 8 bits long at low and full speed or 32 bits long for high speed and is used to synchronize the clock of the receiver with that of the transmitter. The last two bits indicate where the PID fields starts.

PID

PID stands for Packet ID. This field is used to identify the type of packet that is being sent. The following table shows the possible values.

There are 4 bits to the PID, however to insure it is received correctly, the 4 bits are complemented and repeated, making an 8-bit PID in total. The resulting format is shown below.

§         ADDR

The address field specifies which device the packet is designated for. Being 7 bits in length allows for 127 devices to be supported. Address 0 is not valid, as any device which is not yet assigned an address must respond to packets sent to address zero.

§         ENDP

The endpoint field is made up of 4 bits, allowing 16 possible endpoints. Low speed devices, however can only have 2 additional endpoints on top of the default pipe. (4 endpoints max)

§         CRC

Cyclic Redundancy Checks are performed on the data within the packet payload. All token packets have a 5 bit CRC while data packets have a 16 bit CRC.

§         EOP

End of packet. Signaled by a Single Ended Zero (SE0) for approximately 2 bit times followed by a J for 1 bit time.

USB has four different packet types. Token packets indicate the type of transaction to follow, data packets contain the payload, and handshake packets are used for acknowledging data or reporting errors and start of frame packets indicate the start of a new frame.

§         Token Packets

There are three types of token packets,

§         In - Informs the USB device that the host wishes to read information.

§         Out - Informs the USB device that the host wishes to send information.

§         Setup - Used to begin control transfers.

Token Packets must conform to the following format,

§         Data Packets

There are two types of data packets each capable of transmitting up to 1024 bytes of data.

§         Data0

§         Data1

High Speed mode defines another two data PIDs, DATA2 and MDATA.

Data packets have the following format,

§         Maximum data payload size for low-speed devices is 8 bytes.

§         Maximum data payload size for full-speed devices is 1023 bytes.

§         Maximum data payload size for high-speed devices is 1024 bytes.

§         Data must be sent in multiples of bytes.

§         Handshake Packets

There are three types of handshake packets which consist simply of the PID

§         ACK - Acknowledgment that the packet has been successfully received.

§         NAK - Reports that the device temporary cannot send or received data. Also used during interrupt transactions to inform the host there is no data to send.

§         STALL - The device finds its in a state that it requires intervention from the host.

§        

Handshake Packets have the following format,

§         Start of Frame Packets

The SOF packet consisting of an 11-bit frame number is sent by the host every 1ms ± 500ns on a

Full-speed bus.

Specifically, the PM3 enumerates itself as a Human Interface Device (HID) with a control endpoint and two interrupt endpoints (IN/OUT). 

Table 15 - PM3/PM4 USB Definitions

Network and Transport Layers

 

The CSAFE protocol provides both the network and transport layer functionality over USB.  The packetization, integrity checking, and node addressing is supported by the protocol.  The maximum frame size has been increased to 96 bytes from the 32 bytes specified for the asynchronous serial interface.

Protocol Features

 

CSAFE Default Configuration

 

Individual manufacturers specify certain protocol parameters (e.g., timeouts, auto response behavior, etc.).  Table 16 summarizes the protocol defaults for the PM3/PM4.  Note that certain parameters listed in Table 16 cannot be changed (refer to the section on CSAFE Unsupported Features for additional information).

Table 16 - PM3 CSAFE Protocol Defaults

CSAFE State Machine Operation

 

The state machine implementation is shown in

Figure 7 including variations to the behavior specific to the PM3/PM4. 

Figure 7 - CSAFE State Machine Diagram

CSAFE Unsupported Features

 

Individual manufacturers also determine which protocol features will not be supported by their equipment.  Table 17 summarizes the unsupported protocol features and the deviations from other features.  In addition, the status of implementation for each CSAFE command is included in Appendix A.

Table 17 - PM3 Unsupported CSAFE Protocol Features

Command and Response Definitions

 

Workouts

 

Configuring a Programmed Workout

 

The following steps are required to configure the workout parameters and put the PM3/PM4 screen in the proper state prior to rowing commencement:

1.        Set all pertinent workout parameters including either workout time (fixed time workout) or horizontal distance goal (fixed distance workout), and time/distance split duration (if not using default values). Time split duration used for “fixed time” workout and distance split duration used for “fixed distance” workout.

2.        If a power/calories goal is desired to control the paceboat, the proper goal value must be configured. 

3.        Configure the programmed workout using the previously set workout parameters, and direct the PM3/PM4 to initialize the workout display parameters and go to the proper rowing screen in preparation for beginning the workout.

The following is a sample CSAFE command sequence for configuring a 2000m fixed piece with a split duration of 500 m and a power goal of 300 watts:

0x21 0x03 0x02 0x00 0x21      (CSAFE_SETHORIZONTAL_CMD, 2 x Km units specifier)

0x1A 0x07 0x05 0x05 0x80 0xF4 0x01 0x00 0x00

(CSAFE_SETUSERCFG1_CMD,

CSAFE_PM_SET_SPLITDURATION, distance, 500m)

0x34 0x03 0x2C 0x01 0x58     (CSAFE_SETPOWER_CMD, 300 x Watts unit specifier)

0x24 0x02 0x00 0x00                              (CSAFE_SETPROGRAM_CMD, programmed workout)

It is important to issue the SETHORIZONTAL or SETTIME commands prior to setting the split duration because default split duration values are configured by the PM3/PM4 in response to the SETHORIZONTAL and SETTIME commands.

Note that this complete sequence of commands can be combined as follows with the same result:

0x21 0x03 0x02 0x00 0x21 0x1A 0x07 0x05 0x05 0x80 0xF4 0x01 0x00 0x00 0x34 0x03 0x2C 0x01 0x58 0x24 0x02 0x00 0x00

The following is a sample CSAFE command sequence for selecting the first standard list (predefined) workout in the PM3/PM4:

0x24 0x02 0x01 0x00                              (CSAFE_SETPROGRAM_CMD, standard list workout #1)

Programmed Workout Parameter Limits

 

There are several parameters which have minimum and maximum values when configuring a workout.  These parameter limits are imposed by the user interface when configuring the workout during typical usage, but will be imposed somewhat differently when configuring workouts via the public CSAFE interface.  When the SetProgramCmd is issued by the Master to program the previously configured workout, all pertinent workout parameters are checked against their respective limits.  If any parameter violates its limits, the entire workout configuration operation is aborted resulting in a “PrevReject” frame status.  The Master must issue a PM-specific GetErrorType command to determine the specific error information.  Table 18 lists the workout configuration parameter limits which should be adhered to during programming. 

Table 18 - Workout Configuration Parameter Limits

Notes:

1.        The minimum split duration must not cause the total number of splits per workout to exceed the maximum of 30.

2.        The maximum split duration cannot exceed the workout time goal or the horizontal distance goal.

PC-Host Dynamic Link Library (DLL) and Application Programming Interface (API)

 

Overview

 

PC-based host applications can communicate with PM3s over the Universal Serial Bus (USB) using the DLLs.

The following sections describe the architecture and interface details of the DLLs. 

Architecture

 

For User applications, the PM3/PM4 utilizes a protocol architecture based on CSAFE, a protocol that is targeted at supporting communications between physical fitness equipment and a host PC.  Extensions to the CSAFE protocol are employed to provide PM-specific functionality not supported by the generic protocol while maintaining compatibility.

The system architecture also supports other protocols in addition to CSAFE, including PM3/PM4 proprietary protocols for maintenance and system testing.

PM3/PM4 Device Discovery & Interface

 

(PM3DDICP.DLL, PM3DDICP.H, PM3DDICP.LIB)

The PM3/PM4 Device Discovery & Interface DLL is central to all types of applications that communicate with PM3/PM4s.  It provides a means for applications to identify, initialize and communicate with PM3s/PM4s, as well as to discover the network topology upon which the PM3s/PM4s reside.   The Device Discovery interface centralizes the various addressing schemes used by the Media Interfaces, and exposes a unified, global address map to the application.

Incorporated within this DLL is a generic command/response engine as well as an asynchronous interface.  It relies on the other DLLs at the API layer for protocol-specific information (e.g. CSAFE protocol vs. PM3/PM4 proprietary protocol for implementing Flash download).

Media Interfaces

 

These interfaces are generally not called from the application layer, as they are meant to communicate between the Device Discovery Interface and the hardware specific windows drivers.  They provide implementations of communications interfaces specific to the hardware and WDM layers.   Each media interface has unique methods for identifying and addressing PM3s/PM4s.  It is up to the Device Discovery interface to consolidate these unique addressing schemes into a unified address mapping.

USB Interface

 

(PM3USBCP.DLL, PM3USBCP.H, PM3USBCP.LIB)

This media interface implements a Human Interface Device (HID) class connection with the PM3s/PM4s over a USB connection.  The USB HID Class enumeration process performed by the built-in WDM functions provides unique addressing information for each connected PM3/PM4.

802.xx Interface (RF network)

 

(tbd)

Asynchronous Interface (RS232/485)

 

(tbd)

ANT Interface (RF network)

 

(tbd)

CSAFE+ Command Interface

 

(PM3CSAFECP.DLL, PM3CSAFECP.H, PM3CSAFECP.LIB)

The CSAFE+ Command Interface DLL exposes CSAFE commands to the application and provides the proprietary protocol-specific commands/responses that allow the implementation of the CSAFE protocol over the PM3/PM4 network.  Extensions to the CSAFE protocol (hence the name CSAFE+) provide additional proprietary functionality specific to PM3s/PM4s. These proprietary commands are only available if the host PC has performed the prescribed “authentication” process with the PM3/PM4.

The DLL contains the definition and format of all of the supported PM-proprietary CSAFE commands/responses.  When a command is issued by the calling application, the DLL indexes the appropriate command/response object, and passes it to the PM3/PM4 Interface. The PM3/PM4 Interface sends the command via the correct media interface, receives the response data, and then returns it back to the CSAFE DLL, which returns the data to the calling application.

User Application API

 

The PM3/PM4 User Application Programming Interface (API) is based upon and fully supports the CSAFE protocol (see http://www.fitlinxx.com/csafe/specification.htm).  The PM3/PM4 User API is comprised of two DLLs:  one is utilized to provide discovery functions (Version #’s, PM3/PM4 device discovery, addressing and status), and the other is used to implement the CSAFE command set, including an extended version of CSAFE to handle PM-proprietary functionality.

The DLL functions are detailed in the sections below.

PM3/PM4 Device Discovery & Interface API

 

(PM3DDICP.DLL, PM3DDICP.H, PM3DDICP.LIB)

Data Type Definitions

 

The following data types are utilized in this DLL:

unsigned char       UINT8

unsigned short     UINT16

unsigned long      UINT32

char                        INT8

short                       INT16

long                        INT32

unsigned char       BOOLEAN

float32                    FLOAT32

float64                    FLOAT64

INT16_T                ECODE_T

Function Reference

 

tkcmdsetDDI_init

 

About:   Initializes the DLL error code interface and media interfaces (e.g. USB, 802.11, Async).

Inputs:   None

Outputs:                None

Returns: ERRCODE_T   ecode           Zero if successful

Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_init(void);

tkcmdsetDDI_shutdown

 

About:   Shuts down the Command Set Toolkit functions on the specified port.

Inputs:   UINT16_T     port        Communication port to shut down

Outputs:                None

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_shutdown(UINT16_T port);

tkcmdsetDDI_shutdown_all

 

About:   Shuts down the Command Set Toolkit functions on all open ports.

Inputs:   None

Outputs:                None

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_shutdown();

tkcmdsetDDI_discover_pm3s

 

About:   Discover all PM3/PM4 devices connected to the PC via various media interfaces. 

Create a PM3/PM4 device map that correlates consecutive unit identifiers to each device port number and media interface location.  Note that the calling function provides the starting address of the unit ID.

Important note: This function can be called multiple times with different product strings.  The number of devices found will always include ALL devices found previously, even those with different product strings.  Call tkcmdsetDDI_init() before calling this function to reset the “num_units” count back to 0.

Inputs:  INT8_T   *product_name                   Name of product to discover

                UINT16_T    starting_address           Address of first unit

Outputs:                UINT16_T    *num_units                    Number of devices found

Returns: ERRCODE_T   ecode           Zero if successful

Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_discover_pm3s(INT8_T   *product_name , UINT16_T starting_address, UINT16_T *num_units);

tkcmdsetDDI_find_devices

 

About:   Gets port numbers of all USB HID devices that match the product name.

Note that this function shouldn’t generally be used directly by the application.  tkcmdsetDDI_discover_pm3s calls this function as part of the discovery process on all media interfaces.

Inputs:    INT8_T *product_name    Name of USB device to open

Outputs: UINT8_T *num_found      Number of devices that match name

               UINT16_T port_list[]           Port numbers of devices that match

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_find_devices(INT8_T *product_name, UINT8_T *num_found, UINT16_T port_list[])

tkcmdsetDDI_fw_version

 

About:   Reads the firmware version information from the PM3/PM4

Inputs:   UINT16_T  unit_address    Address of PM

                UINT8_T ver_len Length of command in bytes

Outputs:                UINT8_T *   ver_ptr            FW version string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_fw_version(UINT16_T  unit_address, UINT8_T * ver_ptr, UINT8_T ver_len);

tkcmdsetDDI_hw_version

 

About:   Reads the hardware version information from the PM3/PM4

Inputs:   UINT16_T  unit_address    Address of PM

                UINT8_T ver_len Length of command in bytes

Outputs:                UINT8_T *  ver_ptr             HW version string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_hw_version(UINT16_T  unit_address, UINT8_T * ver_ptr, UINT8_T ver_len);

tkcmdsetDDI_loader_fw_version

 

About:   Reads loader firmware version information from the PM3/PM4.

              SUPPORTED ONLY BY PM3 VERSIONS 95 OR GREATER.

Inputs:   UINT16_T     port                 Identifier for device

              INT8_T       ver_len                Length of command in bytes

Outputs:                UINT8_T *   ver_ptr            FW version string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_loader_fw_version(UINT16_T port, INT8_T * ver_ptr, UINT8_T ver_len);

tkcmdsetDDI_serial_number

 

About:   Reads the serial number information from the PM3/PM4.

Inputs:   UINT16_T  unit_address    Address of PM

                UINT8_T ver_len Length of command in bytes

Outputs:                UINT8_T * ser_ptr              Serial number string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_serial_number(UINT16_T  unit_address, UINT8_T * ser_ptr, UINT8_T ver_len);

tkcmdsetDDI_status

 

About:   Reads status information from the PM3/PM4.

Inputs:   UINT16_T     port                 Identifier for device

Outputs:                UINT32_T *  stat_ptr          Location to store status information

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_status(UINT16_T port, UINT32_T *stat_ptr);

tkcmdsetDDI_special

 

About:      Performs special operations based on the command.

Inputs:   UINT16_T  unit_address    Address of PM

                UINT16_T    cmd Special command to execute

                UINT32_T    in_data            Value to send with command

Outputs:                UINT32_T *  out_data        Location to store value returned with response

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_special(UINT16_T  unit_address, UINT16_T cmd, UINT32_T in_data, UINT32_T *out_data);

tkcmdsetDDI_get_dll_version

 

About: Returns the current version number of this DLL.

Inputs:   None

Outputs:                None

Returns: UINT16_T    ver_info          High byte is major version number

                                                                Low byte is minor version number

Function Prototype:

PM3DDI_API UINT16_T tkcmdsetDDI_get_dll_version(void);

tkcmdsetDDI_get_error_name

 

About:   Returns the name of the error associated with the code.

Inputs:   ERRCODE_T   ecode           Code to be looked up

UINT16_T    namelen          Maximum length of name string

Outputs:                char * nameptr      Location to place name string

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_get_error_name(ERRCODE_T ecode,char * nameptr,UINT16_T namelen);

tkcmdsetDDI_get_error_text

 

About:   Returns the text description of the error associated with the code.

Inputs:   ERRCODE_T   ecode           Code to be looked up

                UINT16_T    namelen          Maximum length of text description string

Outputs:                char * nameptr                      Location to place text description string

Returns: ERRCODE_T   ecode           Zero if successful

Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_get_error_text(ERRCODE_T ecode,char * textptr,UINT16_T textlen);

tkcmdsetDDI_init_protocol

 

About:    Initialize a protocol engine that will be used for PM3/PM4

               communications.  This is typically called by an external

               DLL to setup a specific communications protocol.

                NOTE: This is not typically called by the application directly.

                For example, use tkcmdsetCSAFE_init_protocol() instead.

Inputs:    ERRCODE_T   *frame_builder()       Ptr to frame builder function

               ERRCODE_T   *frame_checker()        Ptr to frame checker function

               UINT16_T    timeout             Command/response time out in MS

               UINT16_T    buffer_size                      Max frame size

               UINT8_T     retries                                Number of command retries

Outputs:  None

Returns:  ERRCODE_T   ecode       Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_init_protocol(ERRCODE_T (*) (UINT8_T *, UINT8_T *, UINT16_T *), ERRCODE_T (*) (UINT8_T *, UINT8_T *, UINT16_T *),UINT16_T timeout,  UINT16_T buffer_size, UINT8_T retries);

tkcmdsetDDI_do_protocol

 

About:    Utilizing the protocol engine that was previously setup

               in tkcmdsetDDI_init_protocol(), build and send a command

               frame, then receive and check a response frame.

               If the frame is valid, return the data. 

                This is typically called by an external DLL to implement

a specific communications protocol.  For example,

use tkcmdsetCSAFE_command() instead.

                NOTE: This is not typically called by the application directly.

Inputs:   UINT16_T    port                                  Identifier for device

              UINT16_T    *num_cmd_bytes           Number of data bytes to send

              UINT8_T     *cmd_data                        Data bytes to send

Outputs:UINT16_T    *num_rsp_bytes           Number of received bytes

              UINT8_T     *response                         Response byte

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_do_protocol(UINT16_T port,

                                             UINT16_T *num_cmd_bytes, UINT8_T *cmd_data,

                                             UINT16_T *num_rsp_bytes, UINT8_T *response)

tkcmdsetDDI_do_command

 

About:   Handle the command / response transaction with the device.

                NOTE: This is not typically called by the application directly.

                For example, use tkcmdsetCSAFE_command () instead.

Inputs:   UINT16_T    port Identifier for device

              UINT8_T *   tx_ptr                Pointer to data block to be transmitted

              UINT16_T    tx_len                Number of bytes in the command

              UINT16_T    timeout              Time to wait for response in milliseconds

Outputs:                UINT8_T *   rx_ptr              Pointer to data block to save received data

              UINT16_T*   rx_len               Number of bytes in the response

Returns: ERRCODE_T   ecode       Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_do_command(UINT16_T port, UINT8_T *tx_ptr,

                                            UINT16_T tx_len, UINT8_T *rx_ptr,

                                            UINT16_T * rx_len, UINT16_T timeout);

tkcmdsetDDI_echo

 

About:   Display a message on the PM3/PM4.

Inputs:    UINT16_T    port                 Identifier for device

               UINT8_T *   cmd_ptr           Location of data to send to PM3/PM4

               UINT16_T    cmd_len           Length of data to send

Outputs: Nothing

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_echo(UINT16_T port, UINT8_T * cmd_ptr,

UINT16_T cmd_len);

tkcmdsetDDI_max_report_size

 

About:   Returns the largest USB report size available (buffer size).

Inputs:   UINT16_T port                     Communication port to use

Outputs:                size_ptr                                  Maximum number of bytes available in USB report

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_max_report_size(UINT16_T port, UINT16_T

*size_ptr);

**NOTE: The following asynchronous commands have not been completely validated.

tkcmdsetDDI_do_protocol_async

 

About:   Utilizing the protocol engine that was previously setup

                in tkcmdsetDDI_init_protocol(), build and send a command

                frame asynchronously. 

Inputs:  UINT16_T   port                                    Identifier for device

             UINT16_T   *num_cmd_bytes             Number of data bytes to send

             UINT8_T     *cmd_data                         Data bytes to send

             UINT16_T   cmd_tag                              Identifier to tag this transaction with

Outputs:    Nothing

Returns:    ERRCODE_T   ecode       Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_do_protocol_async(UINT16_T port,                                      UINT16_T *num_cmd_bytes, UINT8_T *cmd_data, UINT16_T cmd_tag);

tkcmdsetDDI_register_asyncio

 

About:   Register a callback for asynchronous I/O functions.

Inputs:   PM3ASYNC_PROC callback             Callback function to receive events

                UINT16_T  timeout                              Time to wait for response in milliseconds

Outputs:                None

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_register_asyncio(PM3ASYNC_PROC callback,

UINT16_T timeout);

tkcmdsetDDI_unregister_asyncio

 

About:   Unregister the asynchronous I/O callback

Inputs:   None

Outputs:                None

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_unregister_asyncio();

tkcmdsetDDI_do_command_async

 

About:      Handle the command transaction with the PM3/PM4 (async interface).

Inputs:   UINT16_T    port Identifier for device

              UINT8_T *   tx_ptr                Pointer to data block to be transmitted

              UINT16_T    tx_len                Number of bytes in the command

              UINT16_T    cmd_tag            Identifier to tag this transaction with

Outputs: Nothing

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3DDI_API ERRCODE_T tkcmdsetDDI_do_command_async(UINT16_T port,  UINT8_T

 *tx_ptr,  UINT16_T tx_len, UINT16_T cmd_tag);

CSAFE Interface API

 

(PM3CSAFECP.DLL, PM3CSAFECP.H, PM3CSAFECP.LIB)

After the DLL has been initialized, the CSAFE+ command set is implemented using a single generic API function.  To accomplish this, the calling application maintains individual command and response buffers (comprised of arrays of 32-bit integers), passing the pointers to these buffers along with PM device addressing and command information (see tkcmdsetCSAFE_command below).

Using CSAFE extended frame addressing, the DLL handles packing CSAFE frames, validating response frames, and unpacking the data into the response array. 

Important: The PM3CSAFECP DLL  recognizes PM-proprietary CSAFE commands to determine the data types expected for commands and responses.  The DLL presents data to the calling application in the return buffer according to type.  For example, if a PM3/PM4 command returns six data bytes comprised as a 2-byte integer and a 4 byte float, the data will be packed in two locations in the return array (one location for each data type).  The DLL also expects command data to be presented in this way, which makes it a simpler interface for the application.

The DLL takes care of formatting the CSAFE frame appropriately, so the application need only send commands and data (see examples below).

The DLL will pass standard CSAFE commands through without modification. Note however, that the calling application must pass the data unpacked, as no data type checking/packing is done by the DLL.  Data count bytes must be included in standard CSAFE commands, whereas the count byte is not needed in PM-proprietary CSAFE commands.

Important: The CSAFE DLL does not currently allow extended CSAFE frames except with PM-proprietary commands.  Extended CSAFE frames (non-PM proprietary) can be sent using the DDI DLL function, “tkcmdsetUSB_do_DDIcommand”.

tkcmdsetCSAFE_init_protocol

 

About:   Initializes the DLL error code interface and configures the CSAFE protocol.  Uses extended frame addressing.

Inputs:   UINT16_T             timeout                   Command/response timeout in MS

                                                                                (defaults to 1000ms (1 sec) if NULL)

Outputs:                None

Returns: ERRCODE_T   ecode                           Zero if successful

Error code otherwise

Function Prototype:

PM3CSAFE_API ERRCODE_T tkcmdsetCSAFE_init_protocol(UINT16_T timeout);

tkcmdsetCSAFE_command

 

About:   Sends a CSAFE command to a PM device and returns

               the response data.  Note: the unit address is previously determined

                using the DiscoverPM3s function in the PM3DDI DLL.

Inputs:   UINT16_T    unit_address                  Address of PM device

              UINT16_T    cmd_data_size                 Size of cmd data    

              UINT32_T    cmd_data[]       Command data

Outputs:UINT16_T    *rsp_data_size              Size of rsp data

              UINT32_T     rsp_data[]                        Response data

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3CSAFE_API ERRCODE_T tkcmdsetCSAFE_command(UINT16_T unit_address,

                                             UINT16_T cmd_data_size, UINT32_T cmd_data[],

                                             UINT16_T *rsp_data_size, UINT32_T rsp_data[]);

tkcmdsetCSAFE_get_dll_version

 

About: Returns the current version number of this DLL.

Inputs:   None

Outputs:                None

Returns: UINT16_T    ver_info          High byte is major version number

                                                                Low byte is minor version number

Function Prototype:

PM3CMD_API UINT16_T tkcmdsetCSAFE_get_dll_version(void);

tkcmdsetCSAFE_get_error_name

 

About:   Returns the name of the error associated with the code

Inputs:   ERRCODE_T   ecode           Code to be looked up

UINT16_T    namelen          Maximum length of name string

Outputs:                char * nameptr      Location to place name string

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3CMD_API ERRCODE_T tkcmdsetCSAFE_get_error_name(ERRCODE_T ecode,char * nameptr,UINT16_T namelen);

tkcmdsetCSAFE_get_error_text

 

About:   Returns the text description of the error associated with the code

Inputs:   ERRCODE_T   ecode           Code to be looked up

                UINT16_T    namelen          Maximum length of text description string

Outputs:                char * nameptr                      Location to place text description string

Returns: ERRCODE_T   ecode           Zero if successful

Error code otherwise

Function Prototype:

PM3CMD_API ERRCODE_T tkcmdsetCSAFE_get_error_text(ERRCODE_T ecode,char * textptr,UINT16_T textlen);

tkcmdsetCSAFE_get_status

 

About:      Gets the CSAFE status byte from the previous transaction.

Inputs:     Nothing

Outputs:    Nothing

Returns:    UINT8_T     slave_status   CSAFE status byte

Function Prototype:

PM3CSAFE_API UINT8_T tkcmdsetCSAFE_get_status(void);

**NOTE: The following asynchronous commands have not been completely validated.

tkcmdsetCSAFE_register_asyncio

 

About:   Register a callback for asynchronous I/O functions.

Inputs:   PM3ASYNC_PROC callback             Callback function to receive events

              UINT16_T timeout                 Time to wait for response in milliseconds

Outputs:                None

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3CSAFE_API ERRCODE_T tkcmdsetCSAFE_register_asyncio(PM3ASYNC_CSAFE_PROC callback, UINT16_T timeout);

tkcmdsetCSAFE_unregister_asyncio

 

About:      Unregister the asynchronous I/O callback

Inputs:     None

Outputs:    None

Returns:    ERRCODE_T   ecode       Zero if successful

                                       Error code otherwise

Function Prototype:

PM3CSAFE_API ERRCODE_T tkcmdsetCSAFE_unregister_asyncio();

PM3 USB Interface API

 

(PM3USBCP.DLL, PM3USBCP.H, PM3USBCP.LIB)

The following is the API for the USB DLL.  NOTE: The functions in this DLL are not typically called by the application (the API layer DDI DLL calls these functions).  CALLING DIRECTLY TO THE USB DLL FUNCTIONS IS RECOMMENDED ONLY FOR ADVANCED USERS!

Note that the complete CSAFE frame must be properly formatted (including byte stuffing and checksum!) when using this direct interface to communicate with the PM3/PM4.

tkcmdsetUSB_get_dll_version()

 

About:   Returns the current version number of this software.

Inputs:   None

Outputs:                None

Returns: UINT16_T    ver_info          High byte is major version number

                                                                Low byte is minor version number

Function Prototype:

PM3USB_API UINT16_T tkcmdsetUSB_get_dll_version(void);

tkcmdsetUSB_get_error_name

 

About:   Returns the name of the error associated with the code

Inputs:   ERRCODE_T   ecode           Code to be looked up

UINT16_T    namelen          Maximum length of name string

Outputs:    char *      nameptr             Location to place name string

Returns:    ERRCODE_T   ecode        Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API void tkcmdsetUSB_get_error_name(ERRCODE_T ecode,char * nameptr,                                     UINT16_T namelen);

tkcmdsetUSB_get_error_text

 

About:   Returns the text description of the error associated with the code

Inputs:   ERRCODE_T   ecode           Code to be looked up

UINT16_T    namelen          Maximum length of text description string

Outputs:    char *      nameptr             Location to place text description string

Returns:    ERRCODE_T   ecode     Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API void tkcmdsetUSB_get_error_text(ERRCODE_T ecode,char * textptr,                                           UINT16_T textlen);

tkcmdsetUSB_init

 

About:   Initializes the Command Set Toolkit functions.

Inputs:   None

Outputs: None

Returns: ERRCODE_T        ecode     Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_init();

tkcmdsetUSB_find_devices

 

About:   Gets port numbers of all USB HID devices that match the product name.

Inputs:   INT8_T *    product_name                 Name of USB device to open

Outputs: UINT8_T *   num_found                   Number of devices that match name

               UINT16_T    port_list[]                        Port numbers of devices that match

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_find_devices(INT8_T *product_name, UINT8_T *num_found, UINT16_T port_list[]);

tkcmdsetUSB_do_DDIcommand

 

About:      Handle the command / response transaction with the device.

Inputs:     UINT16_T    port                Identifier for device

               UINT8_T *   tx_ptr               Pointer to data block to be transmitted

               UINT16_T    tx_len               Number of bytes in the command

               UINT16_T    timeout             Time to wait for response in milliseconds

Outputs:    UINT8_T *   rx_ptr           Pointer to data block to save received data

               UINT16_T*   rx_len              Number of bytes in the response

Returns:    ERRCODE_T   ecode        Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_do_DDIcommand(UINT16_T port, UINT8_T

*tx_ptr, UINT16_T tx_len, UINT8_T *rx_ptr, UINT16_T * rx_len, UINT16_T timeout)

tkcmdsetUSB_status

 

About:   Reads status information from the device

Inputs:   UINT16_T    port                  Identifier for device

Outputs:                UINT32_T *  stat_ptr          Location to store status information

Returns: ERRCODE_T   ecode           Zero if successful

Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_status(UINT16_T port, UINT32_T *stat_ptr);

tkcmdsetUSB_fw_version

 

About:   Reads the firmware version information from the PM3/PM4

Inputs:   UINT16_T    port                  Communication port to use

Outputs:                UINT8_T *   ver_ptr            FW version string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_fw_version(UINT16_T port, INT8_T * ver_ptr, UINT8_T ver_len);

tkcmdsetUSB_hw_version

 

About:      Reads the hardware version information from the PM3/PM4

Inputs:   UINT16_T     port                 Communication port to use

Outputs:                UINT8_T *   ver_ptr            HW version string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_hw_version(UINT16_T port, INT8_T * ver_ptr, UINT8_T ver_len);

tkcmdsetDDI_serial_number

 

About:   Reads the serial number information from the PM3/PM4

Inputs:   UINT16_T    port                  Communication port to use

Outputs:                UINT8_T *   ser_ptr            Serial number string stored at this location

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_serial_number(UINT16_T port, INT8_T * ser_ptr, UINT8_T ser_len);

tkcmdsetUSB_shutdown

 

About:   Shuts down the Command Set Toolkit functions

Inputs:   UINT16_T    port                  Communication port to use

Outputs:                None

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_shutdown(UINT16_T port);

**NOTE: The following asynchronous commands have not been completely validated.

tkcmdsetUSB_register_asyncio

 

About:   Register a callback for asynchronous I/O functions.

Inputs:   PM3ASYNC_PROC callback             Callback function to receive events

              UINT16_T timeout                 Time to wait for response in milliseconds

Outputs:                None

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_register_asyncio(PM3ASYNC_PROC callback, UINT16_T timeout);

tkcmdsetUSB_unregister_asyncio

 

About:   Unregister the asynchronous I/O callback

Inputs:   None

Outputs:                None

Returns: ERRCODE_T   ecode           Zero if successful

                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_unregister_asyncio();

tkcmdsetUSB_send_command

 

About:   Send an asynchronous command to the USB device.

Inputs:   UINT16_T    port                                  Identifier for device

                UINT8_T *   tx_ptr                              Pointer to data block to be transmitted

                UINT16_T   tx_len                               Transmit buffer length

                UINT16_T cmd_tag                             Identifier Tag to pass back to the caller on recv

Outputs: None

Returns: ERRCODE_T   ecode                           Zero if successful

                                                                                Error code otherwise

Function Prototype:

PM3USB_API ERRCODE_T tkcmdsetUSB_send_command(UINT16_T port, UINT8_T *tx_ptr, UINT16_T tx_len, UINT16_T cmd_tag);

Example Application Logic – CSAFE DLLs.

 

The following demonstrates setup and operation of the CSAFE DLLs.

/* Initialize the DLL and media (hardware) interfaces */

if (ecode = tkcmdsetDDI_init())

{

                /* PM3 DLL init error */

}

/* Discover and get count of all discovered PM3s or PM4s.  Tell DLL to start numbering at 0. */

else if((ecode = tkcmdsetDDI_discover_pm3s(TKCMDSET_PM3_PRODUCT_NAME2, 0, &num_units)

           &&

           (ecode = tkcmdsetDDI_discover_pm3s(TKCMDSET_PM4_PRODUCT_NAME, 0, &num_units))

{

                /* PM discovery error */

tkcmdsetDDI_shutdown();

}

/* Initialize the CSAFE protocol engine.  Leave timeout at default. */

else if (ecode = tkcmdsetCSAFE_init_protocol())

{

                /* CSAFE DLL init error */

}

/* Program loop */

else

{

                /* (PM initialization goes here, using CSAFE commands) */

                while (program_is_running)

                {

                                /*

 * Example command : CSAFE_GETHORIZONTAL_CMD

 *

 *  Where:

 *             unit_address = 0;

*              cmd_data[] = {0xA1}; // (CSAFE_GETHORIZONTAL_CMD)

 *             cmd_size = 1;

 */

tkcmdsetCSAFE _command(unit_address, cmd_size, cmd_data, &rsp_size, rsp_data);

/*

 * Example response data:

 *             rsp_data[] = {0xD0, 0x07, 0x24};                        // (Horizontal LS byte,

//  Horizontal MS byte,

 *                                                                                             //  Unit Specifier)

 *             rsp_size = 3;

*/

                }

                /* Clean up and exit */

tkcmdset_shutdown();

}

Example Application Logic – USB DLL (“direct interface”).

 

The following demonstrates calling directly into the USB DLL, bypassing the CSAFE and DDI DLLs.  Note that the complete CSAFE frame must be properly formatted (including byte stuffing!) when using this direct interface to communicate with the PM3/PM4.

/* Initialize the USB DLL interface */

if ((ecode = tkcmdsetUSB_init()

{

                /* USB init error – shut down DLL */

tkcmdsetUSB_shutdown();

}

/* Initialize and discover USB PM3 devices. Update device map structure.*/

/* usb_port[] is an array of USB port numbers for all PM3’s found - will get populated by this routine */

else if ((ecode = tkcmdsetUSB_find_devices (TKCMDSET_PM3_PRODUCT_NAME2, &usb_num_units, usb_port) &&

     (ecode = tkcmdsetUSB_find_devices (TKCMDSET_PM4_PRODUCT_NAME, &usb_num_units, usb_port))

{

                /* Find devices error – shut down DLL */

tkcmdsetUSB_shutdown();

}

else

{

                /* (PM initialization goes here, using CSAFE commands) */

                while (program_is_running)

                {

                                /*

 * Example command : GET STATUS (uses extended frame format)

*  Where:

 *             usb_port[0] = 0;

 *             timeout = 70; (in ms)

 *             cmd_data[] = {0xF0, 0xFD, 0x00, 0x80, 0x80, 0xF2}; // GET STATUS

*              cmd_len = 6;

*              rsp_len = 100; (this is used by DLL to determine USB report size)

*             

*/

ecode = tkcmdsetUSB_do_DDIcommand(usb_port[0], cmd_data, cmd_len, rsp_data, &rsp_len, timeout);

/* Example response data:

 *             rsp_data[] = { 0xF0, 0x00, 0xFD, 0x01, 0x80, 0x01, 0x01, 0x81, 0xF2};

*/

                }

                /* Clean up and exit */

tkcmdsetUSB_shutdown();

}

Appendix A

 

CSAFE Commands Implemented

 

Short Commands

 

Notes:

1.        No specific response data, but the status byte will be returned

2.        Depends on # ID digits configuration

Example CSAFE command/response frames using standard frame:

Get status using the CSAFE_GETSTATUS_CMD command -

Command Frame: 0xF1 0x80 0x80 0xF2

Response Frame: 0xF1 0x01 0x80 0x01 0x01 0x81 0xF2

Example CSAFE command/response frames using extended frames with the host PC address of 0x00 and the default PM (Erg) address of 0xFD:

Get version information using the CSAFE_GETVERSION_CMD command -

Command Frame: 0xF0 0xFD 0x00 0x91 0x91 0xF2

Response Frame: 0xF0 0x00 0xFD 0x81 0x91 0x07 0x16 0x02 0x03 0xA4 0x01 0x84 0x03 0xA3 0xF2

Long Commands

 

Notes:

1.        Used for PM-specific functionality as command wrapper

2.        Although implemented, this command currently has no affect

3.        Added for PM proprietary functionality as command wrappers (not available for public use except for specifically designated public commands)

Example CSAFE command/response frame using standard frame:

Set work time goal to 7:30 with CSAFE_SETTWORK_CMD command -

Command Frame: 0xF1 0x20 0x03 0x00 0x07 0x1E 0x3A 0xF2

Response Frame: 0xF1 0x01 0x05 0x80 0x02 0x00 0x01 0xF9 0xF2

Example CSAFE command/response frame using extended frame with the host PC address of 0x00 and the default PM (Erg) address of 0xFD:

Get device protocol parameter capabilities with the CSAFE_GETCAPS_CMD command -

Command Frame: 0xF0 0xFD 0x00 0x70 0x01 0x00 0x71 0xF2

Response Frame: 0xF0 0x00 0xFD 0x81 0x70 0x03 0x60 0x60 0x032 0x41 0xF2

CSAFE PM3-Specific Commands Implemented

 

Short Commands

 

Notes:

1.        The above commands are sent using the CSAFE_SETUSERCFG1_CMD command wrapper discussed in PM3 Extensions.

2.        The ERRORVALUE command will serve to clear the latched error value in the PM3 when the Screen Error Display Mode is DISABLED

Example CSAFE command/response frame using standard frame:

Get higher resolution work time (2:30.85 seconds) using the CSAFE_SETUSERCFG1_CMD command wrapper with a CSAFE_PM_GET_WORKTIME command -

Command Frame: 0xF1 0x1A 0x01 0xA0 0xBB 0xF2

Response Frame: 0xF1 0x81 0x1A 0x07 0xA0 0x05 0x98 0x3A 0x00 0x00 0x55 0x4F 0xF2

Example CSAFE command/response frames using extended frames with the host PC address of 0x00 and the default PM (Erg) address of 0xFD:

Get workout type (fixed distance w/ splits) and drag factor (128) using the CSAFE_SETUSERCFG1_CMD command wrapper with a CSAFE_PM_GET_WORKOUTTYPE and CSAFE_PM_GET_DRAGFACTOR commands  -

Command Frame: 0xF0 0xFD 0x00 0x1A 0x02 0x89 0xC1 0x50 0xF2

Response Frame: 0xF0 0x00 0xFD 0x01 0x1A 0x06 0x89 0x01 0x03 0xC1 0x01 0x80 0xD7 0xF2

Long Commands

 

Notes:

1.        The above commands are sent using the CSAFE_SETUSERCFG1_CMD command wrapper discussed in PM3 Extensions.

2.        A maximum block length of 32 bytes (16 words) can be read. Fewer words can be read by specifying the block length accordingly, but a complete 33 bytes of response data will be returned.  The first byte of the response will indicate how many valid data bytes are returned.

3.        A maximum block length of 32 bytes (16 words) can be read. Fewer words can be read by specifying the block length accordingly, but a complete 33 bytes of response data will be returned.  Only data samples recorded since the last read will be returned.  The first byte of the response will indicate how many valid data bytes are returned.   

Example CSAFE command/response frame using standard frame:

Set the split duration  (100 m) using the CSAFE_SETUSERCFG1_CMD command wrapper with a CSAFE_PM_SET_SPLITDURATION command  -

Command Frame: 0xF1 0x1A 0x07 0x05 0x05 0x80 0x64 0x00 0x00 0x00 0xF9 0xF2

Response Frame: 0xF1 0x81 0x1A 0x01 0x05 0x1E 0xF2

Appendix B

 

PM3 Data Conversions

 

Watts <-> Pace

 

Pace is in sec/meter:   

Watts = (2.8 / ( pace * pace * pace ))

Calories/Hr <-> Pace

 

Pace is in sec/meter:   

Calories/Hr = (((2.8 / ( pace * pace * pace )) * ( 4.0 * 0.8604)) + 300.0)

Pace <-> /500m Pace

 

Pace is in sec/meter:   

                Pace/500m = (pace * 500)

Appendix C

 

Pre-programmed workout definitions for standard list and custom list are defined below.  Note that the "Custom List" and "Favorites" workouts can vary from PM to PM depending on actions taken by the user.

Standard List Workouts

 

Program # / Description

1 - 2000m Fixed Distance with 500m splits

2 - 5000m Fixed Distance with 1000m splits

3 - 10000m Fixed Distance with 2000m splits

4 - 30:00 Fixed Time w/ 6:00 splits

5 - 500m Fixed Distance Interval with 1:00 rest between intervals (500m/1:00r)

Custom List Workouts

 

Program # / Description

6 - 00:30 Fixed Time Interval w/ 00:30 rest between intervals (:30/:30r)

7 - 7 Interval Variable (1:00/1:00r, 2:00/2:00r, 3:00/3:00r, 4:00/4:00r, 3:00/3:00r, 2:00/2:00r, 1:00/1:00r)

8 - 4 Interval Variable (2000m/3:00r, 1500m/3:00r, 1000m/3:00r, 500m/3:00r)

9 - 9 Interval Variable (1:40/:20r, 1:40/:20r, 1:40/:20r, 1:40/:20r, 1:40/2:00r, 1:40/:20r, 1:40/:20r, 1:40/:20r, 1:40/:20r)

10 - 42195 Fixed Distance with 2000m splits

Appendix D

 

The PM3/PM4 error display format is a combination of error code and screen number as defined below:

                                                <Error Code> - <Screen Number>

The error codes and their descriptions are provided in Table 19.

PM3/PM4 Error Codes

 

Table 19 - PM3/PM4 Error Code Descriptions