Hatteland HT B22 User Manual

Page 1 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

HD CAN Module

Programmer’s Guide

(Windows)

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 2 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

INDEX

INDEX .......................................................................................................................................... 2

Revision History ............................................................................................................................ 3

Abbreviation .................................................................................................................................. 3

1. Introduction .......................................................................................................................... 4

2. Usage of CAN Library ............................................................................................................. 5

3. Example Application .............................................................................................................. 6

4. Appendix .............................................................................................................................16

Page 3 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

Revision History

Abbreviation

Description

Created

Approved

Rev

Date

By

Date

By

Description

1

2013.08.18

Wei Jing

2013.09.25

Joakim
Emanuelsson

Preliminary Version
HD CAN Library V1.0.216

2

2013.09.25

Wei Jing

2013-09-25

Joakim
Emanuelsson

HD CAN Library V1.0.224

CAN FW V1.1

- Add Software Reset

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Abbreviation

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 4 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

1. Introduction

Along with the Hatteland Display external CAN module, a library set is provided for customized
development under Windows environment. It provides the full control of the target CAN module, such
as Device Open/Close, Communication Module Connect/Disconnect, Message Send/Receive and
Periodic Message send.
The Library for CAN module is provided in the form of dynamic library (.dll) for Windows. The
programmer has to perform certain settings to make sure it is linked in the project.
In addition, here comes with an example test application to introduce how to initialize and call all the
APIs for CAN module.
In the Appendix, the full API maps are listed.
The CAN Library is supporting the following OSs:

Windows XP, 32 bit, SP2c
Windows XP, 32 bit, SP3
Windows 7, 32 bit
Windows 7, 64 bit

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 5 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

2. Usage of CAN Library

2.1 Installation

In order to install software for USB–CAN Gateway following steps should be performed:

Run setup file named

operating systems listed in Chap 1),

Select components to install (CAN Driver and API are obligatory, SWDL is optional),
Finish the installation.

After installation Hatteland_CAN.inf file (needed for USB-CAN Gateway installation) should be
present in /Windows/inf directory and /Program Files/Hatteland/CAN_Driver directory.
HDJ2534.dll file should be present in /Windows/system32 directory. SWDL.exe application should be
present in /Program Files/Hatteland/CAN_Driver directory (only if selected during installation).

2.2 Link

The Library for HD CAN module is provided in the form of dynamic library under Windows. After the
programmer follows the installation instruction as above, the file should be correctly linked into the
developing project.

Call

LoadLibrary(“HDJ2534x86(x64).dll”)

Hatteland_CAN_Driver_Setup-1.0.216.exe

as normal Windows application

(common for

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 6 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

3. Example Application

/**************************************************************************
**********//**
* @file test_demo_CAN.cpp
* @brief Demo application for HD CAN Module
* @date 2013-09-24
* @copyright Hatteland Display AS

***************************************************************************
************/

#include "hdj2534Handler.h"
#include <string.h>
#include <iostream>
#include <iomanip>
#include <string>
#include <fstream>

//#include "hdj2534.h"

#define FAKE_CHANNEL_ID 123
#define FAKE_DEVICE_ID 0
#define FAKE_PTR 0
#define FAKE_FLAGS 0xFFFFFF
#define PERIODIC_MSG_NUM 15
#define FILTER_NUM 15
#define PASSTHRU_MSG_NUM 256
#define ID_BYTES_NUM 4
#define INITIAL_MSG_ID 0xFFFFFF
#define INITIAL_FILTER_ID 0xFFFFFF

using namespace std;
using namespace J2534;

/** @brief J2534 PassThru function name strings */

const char *passThruFuncNames[16] =

{

"PassThruOpen()",
"PassThruClose()",
"PassThruConnect()",
"PassThruDisconnect()",
"PassThruReadMsgs()",
"PassThruWriteMsgs()",
"PassThruStartPeriodicMsg()",
"PassThruStopPeriodicMsg()",
"PassThruStartMsgFilter()",
"PassThruStopMsgFilter()",
"PassThruSetProgrammingVoltage()",
"PassThruReadVersion()",
"PassThruGetLastError()",
"PassThruIoctl()",
"PassThruGetStatus()",
"PassThruReset()",
"\0",

};

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 7 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

/** @brief J2534 PassThru function numbers */

enum passThruFuncNum

{

NO_FUNCTION = 0,
PASSTHRU_OPEN,
PASSTHRU_CLOSE,
PASSTHRU_CONNECT,
PASSTHRU_DISCONNECT,
PASSTHRU_READ_MSG,
PASSTHRU_WRITE_MSG,
PASSTHRU_START_PERIODIC_MSG,
PASSTHRU_STOP_PERIODIC_MSG,
PASSTHRU_START_MSG_FILTER,
PASSTHRU_STOP_MSG_FILTER,
PASSTHRU_SET_PROGRAMMING_VOLTAGE,
PASSTHRU_READ_VERSION,
PASSTHRU_GET_LAST_ERROR,
PASSTHRU_IOCTL,
PASSTHRU_GET_STATUS,
PASSTHRU_RESET,

};

static unsigned long deviceId;
static unsigned long channel_1;
static unsigned long channel_2;
static unsigned long filterId[FILTER_NUM];
static unsigned long periodMsgId[PERIODIC_MSG_NUM];
static PASSTHRU_MSG txPassThruMsg[PASSTHRU_MSG_NUM];
static PASSTHRU_MSG rxPassThruMsg[PASSTHRU_MSG_NUM];
static PASSTHRU_MSG filterMaskPassThruMsg;
static PASSTHRU_MSG filterPattPassThruMsg;

static void callPassThruOpen();
static void callPassThruClose();
static void callPassThruConnect();
static void callPassThruDisconnect();
static void callPassThruReadMsgs();
static void callPassThruWriteMsgs();
static void callPassThruStartMsgFilter();
static void callPassThruStopMsgFilter();

HINSTANCE dllLib;

PassThruOpen_t PassThruOpen;
PassThruClose_t PassThruClose;
PassThruConnect_t PassThruConnect;
PassThruDisconnect_t PassThruDisconnect;
PassThruReadMsgs_t PassThruReadMsgs;
PassThruWriteMsgs_t PassThruWriteMsgs;
PassThruGetLastError_t PassThruGetLastError;
PassThruStartPeriodicMsg_t PassThruStartPeriodicMsg;
PassThruStopPeriodicMsg_t PassThruStopPeriodicMsg;
PassThruStartMsgFilter_t PassThruStartMsgFilter;
PassThruStopMsgFilter_t PassThruStopMsgFilter;
PassThruIoctl_t PassThruIoctl;
PassThruSetProgrammingVoltage_t PassThruSetProgrammingVoltage;
PassThruReadVersion_t PassThruReadVersion;

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 8 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

PassThruGetStatus_t PassThruGetStatus;
PassThruReset_t PassThruReset;
_J2534_ERROR_CODE err;

bool freeLib()

{

if (NULL != dllLib)
{
if (FreeLibrary(dllLib) == NULL)
{
return false;
}
dllLib = NULL;
}
return true;

}

bool loadLib()

{

#ifdef _WIN64

dllLib = LoadLibrary(TEXT("HDJ2534x64.dll"));

#else

dllLib = LoadLibrary(TEXT("HDJ2534x86.dll"));

#endif

if (dllLib == NULL)
{
cout << "Unable to load DLL!" << endl;
return false;
}

PassThruOpen = (PassThruOpen_t)GetProcAddress(dllLib,

"PassThruOpen");

PassThruClose = (PassThruClose_t)GetProcAddress(dllLib,

"PassThruClose");

PassThruConnect = (PassThruConnect_t)GetProcAddress(dllLib,

"PassThruConnect");

PassThruDisconnect = (PassThruDisconnect_t)GetProcAddress(dllLib,

"PassThruDisconnect");

PassThruReadMsgs = (PassThruReadMsgs_t)GetProcAddress(dllLib,

"PassThruReadMsgs");

PassThruWriteMsgs = (PassThruWriteMsgs_t)GetProcAddress(dllLib,

"PassThruWriteMsgs");

PassThruGetLastError = (PassThruGetLastError_t)GetProcAddress(dllLib,

"PassThruGetLastError");

PassThruStartPeriodicMsg =

(PassThruStartPeriodicMsg_t)GetProcAddress(dllLib,

"PassThruStartPeriodicMsg");

PassThruStopPeriodicMsg =

(PassThruStopPeriodicMsg_t)GetProcAddress(dllLib,

"PassThruStopPeriodicMsg");

PassThruStartMsgFilter =

(PassThruStartMsgFilter_t)GetProcAddress(dllLib, "PassThruStartMsgFilter");

PassThruStopMsgFilter =

(PassThruStopMsgFilter_t)GetProcAddress(dllLib, "PassThruStopMsgFilter");

PassThruIoctl =

(PassThruIoctl_t)GetProcAddress(dllLib,"PassThruIoctl");

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 9 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

PassThruSetProgrammingVoltage =

(PassThruSetProgrammingVoltage_t)GetProcAddress(dllLib,"PassThruSetProgramm

ingVoltage");

PassThruReadVersion =

(PassThruReadVersion_t)GetProcAddress(dllLib,"PassThruReadVersion");

PassThruGetStatus =

(PassThruGetStatus_t)GetProcAddress(dllLib,"PassThruGetStatus");

PassThruReset =

(PassThruReset_t)GetProcAddress(dllLib,"PassThruReset");

if ((PassThruOpen == NULL) ||
(PassThruClose == NULL) ||
(PassThruConnect == NULL) ||
(PassThruDisconnect == NULL) ||
(PassThruReadMsgs == NULL) ||
(PassThruWriteMsgs == NULL) ||
(PassThruGetLastError == NULL) ||
(PassThruStartPeriodicMsg == NULL) ||
(PassThruStopPeriodicMsg == NULL) ||
(PassThruStartMsgFilter == NULL) ||
(PassThruStopMsgFilter == NULL) ||
(PassThruReset == NULL))
{
cout << "Unable to find DLL function!" << endl;
if (false == freeLib())
{
cout << "Unable to free DLL!" << endl;
}
return false;
}
return true;

}

/**************************************************************************
**********//**
* @brief Function to Open device

***************************************************************************
************/

static void callPassThruOpen()

{

PassThruOpen(0, &deviceId);

}

/**************************************************************************
**********//**
* @brief Function to Close Device

***************************************************************************
************/

static void callPassThruClose()

{

PassThruClose(deviceId);

}

/**************************************************************************
**********//**
* @brief Function to Connect Channel

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 10 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

***************************************************************************
************/

static void callPassThruConnect()

{

int baudSel;
int protoSel;
int chanSel;
int devSel;
int flagSel;
unsigned long deviceIdToUse;
unsigned long baudrate;
unsigned long flags;

//"Enter protocol (0-J1850VPW, 1-J1850PWM, 2-ISO9141, 3-ISO14230, 4-

CAN, 5-ISO15765, "

// "6-SCI_A_ENGINE, 7-SCI_A_TRANS, 8-SCI_B_ENGINE, 9-

SCI_B_TRANS): ";

//Select CAN protocol
protoSel = 4;
//cout << "Enter baudrate (0-125kbps, 1-250kbps, 2-500kbps, 3-1Mbps,

4-invalid baudrate): ";

baudSel = 125000;

flags = PHYSICAL_CHANNEL;

deviceIdToUse = deviceId;

PassThruConnect(deviceIdToUse, static_cast<J2534_PROTOCOL>(protoSel +

1), flags, baudrate, &channel_1);

}

/**************************************************************************
**********//**
* @brief Function to disconnect channel

***************************************************************************
************/

static void callPassThruDisconnect()

{

PassThruDisconnect(channel_1);

}

/**************************************************************************
**********//**
* @brief Function to Read Message

***************************************************************************
************/

static void callPassThruReadMsgs()

{

unsigned long msgNum = 1;
unsigned long *msgNumPtr = &msgNum;
unsigned long timeout = 0;
unsigned int id = 0x10;
int chanSel;
int msgPtrSel;
int msgNumPtrSel;

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 11 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

J2534_ERROR_CODE err;
PASSTHRU_MSG *rxPassThruMsgPtr = rxPassThruMsg;
J2534_RxStatus rxStatus;

err = PassThruReadMsgs(channel_1, rxPassThruMsgPtr, msgNumPtr,
timeout);

if (err == STATUS_NOERROR)
{
if (msgNum != 0)
{
for (unsigned int i = 0; i < msgNum; i++)
{
id = rxPassThruMsg[i].Data[0] << 24;
id |= rxPassThruMsg[i].Data[1] << 16;
id |= rxPassThruMsg[i].Data[2] << 8;
id |= rxPassThruMsg[i].Data[3] << 0;
cout << hex << uppercase;
cout << "ID:" << setfill('0') << setw(ID_BYTES_NUM

* 2) << id << "\t";

cout << "DLC:" << setfill('0') << setw(2) <<

(rxPassThruMsg[i].DataSize - ID_BYTES_NUM) << "\t";

cout << "MSG:";
for (unsigned int j = ID_BYTES_NUM; j <
rxPassThruMsg[i].DataSize; j++)
{
cout << setfill('0') << setw(2) <<

(int)rxPassThruMsg[i].Data[j] << " ";

}
cout << dec;
cout << "\t";
cout << "TYPE:";
rxStatus.value = rxPassThruMsg[i].RxStatus;
if (rxStatus.bits.Can29BitId == 0)
{
cout << "STD" << endl;
}
else
{
cout << "EXT" << endl;
}
}
}
else
{
cout << "No message has been received" << endl;
}
}

}

/**************************************************************************
**********//**
* @brief Function to Write Messages

***************************************************************************
************/

static void callPassThruWriteMsgs()

{

unsigned int id = 0x10;

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 12 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

unsigned long msgNum = 1;
unsigned long *msgNumPtr = &msgNum;
unsigned int dlc = 1;
J2534_ConnectFlags txFlags;
unsigned long timeout = 0;;
int addrSel;
int chanSel;
int msgPtrSel;
int msgNumPtrSel;
int protoSel;
PASSTHRU_MSG *txPassThruMsgPtr = txPassThruMsg;

//"Enter protocol (0-J1850VPW, 1-J1850PWM, 2-ISO9141, 3-ISO14230, 4-

CAN, 5-ISO15765, "

// "6-SCI_A_ENGINE, 7-SCI_A_TRANS, 8-SCI_B_ENGINE, 9-

SCI_B_TRANS): ";

protoSel = 4;

//Set message Data
txPassThruMsg[0].Data[ID_BYTES_NUM + 0] = static_cast<unsigned

char>(0x12);

//Standard message length
txFlags.bits.Can29BitId = 0;

txPassThruMsg[0].TxFlags = txFlags.value;
txPassThruMsg[0].DataSize = dlc + ID_BYTES_NUM;
txPassThruMsg[0].ProtocolID = static_cast<J2534_PROTOCOL>(protoSel +

1);

for (unsigned int i = 0; i < msgNum; i++)
{
txPassThruMsg[i] = txPassThruMsg[0];
txPassThruMsg[i].Data[0] = static_cast<unsigned char>(id >>

24);

txPassThruMsg[i].Data[1] = static_cast<unsigned char>(id >>

16);

txPassThruMsg[i].Data[2] = static_cast<unsigned char>(id >> 8);
txPassThruMsg[i].Data[3] = static_cast<unsigned char>(id >> 0);
id++;
}
//Send Message via Channel_1
PassThruWriteMsgs(channel_1, txPassThruMsgPtr, msgNumPtr, timeout);

}

/**************************************************************************
**********//**
* @brief Function to start msg filter

***************************************************************************
************/

static void callPassThruStartMsgFilter()

{

int protoSel;
int addrSel;
int chanSel;
int filterIdSel = 0;
int filterTypeSel = PASS_FILTER;

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 13 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

unsigned int maskId = 0;
unsigned int pattId = 0;
int msgPtrSel;
PASSTHRU_MSG *filterMaskPassThruMsgPtr = &filterMaskPassThruMsg;
PASSTHRU_MSG *filterPattPassThruMsgPtr = &filterPattPassThruMsg;
J2534_ConnectFlags filterFlags;
J2534_FILTER filterType;

memset((void *)&filterMaskPassThruMsg, 0, sizeof
filterMaskPassThruMsg);
memset((void *)&filterPattPassThruMsg, 0, sizeof
filterPattPassThruMsg);

//Select CAN protocol
//"Enter protocol (0-J1850VPW, 1-J1850PWM, 2-ISO9141, 3-ISO14230, 4-

CAN, 5-ISO15765, "

// "6-SCI_A_ENGINE, 7-SCI_A_TRANS, 8-SCI_B_ENGINE, 9-

SCI_B_TRANS): ";

protoSel = 4;
filterMaskPassThruMsg.ProtocolID =

static_cast<J2534_PROTOCOL>(protoSel + 1);

filterPattPassThruMsg.ProtocolID =

static_cast<J2534_PROTOCOL>(protoSel + 1);

filterMaskPassThruMsg.DataSize = ID_BYTES_NUM;

filterPattPassThruMsg.DataSize = ID_BYTES_NUM;

for (unsigned int i = 0; i < 4; i++)
{
filterMaskPassThruMsg.Data[ID_BYTES_NUM + i] = 0;
}

for (unsigned int i = 0; i < 4; i++)
{
filterPattPassThruMsg.Data[ID_BYTES_NUM + i] = 0;
}

filterMaskPassThruMsg.Data[0] = static_cast<unsigned char>(maskId >>

24);

filterMaskPassThruMsg.Data[1] = static_cast<unsigned char>(maskId >>

16);

filterMaskPassThruMsg.Data[2] = static_cast<unsigned char>(maskId >>

8);

filterMaskPassThruMsg.Data[3] = static_cast<unsigned char>(maskId >>

0);

filterPattPassThruMsg.Data[0] = static_cast<unsigned char>(pattId >>

24);

filterPattPassThruMsg.Data[1] = static_cast<unsigned char>(pattId >>

16);

filterPattPassThruMsg.Data[2] = static_cast<unsigned char>(pattId >>

8);

filterPattPassThruMsg.Data[3] = static_cast<unsigned char>(pattId >>

0);

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 14 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

//Set Standard ID(0/Standard;1/Extended)
filterFlags.bits.Can29BitId = 0;

filterMaskPassThruMsg.TxFlags = filterFlags.value;

filterFlags.bits.Can29BitId = 0;

filterPattPassThruMsg.TxFlags = filterFlags.value;

PassThruStartMsgFilter(channel_1, filterType,
filterMaskPassThruMsgPtr, filterPattPassThruMsgPtr, NULL,

&filterId[filterIdSel]);

}

/**************************************************************************
**********//**
* @brief Function to stop message filter

***************************************************************************
************/

static void callPassThruStopMsgFilter()

{

int filterIdSel = 0;
J2534_ERROR_CODE err;

err = PassThruStopMsgFilter(channel_1, filterId[filterIdSel]);

if (STATUS_NOERROR == err)
{
filterId[filterIdSel] = INITIAL_FILTER_ID;
}

}

/**************************************************************************
**********//**
* @brief Function to do software reset

***************************************************************************
************/

static void callPassThruReset()

{

PassThruReset();

}

int main(void)

{

//Load Library
if(!loadLib())
{
cout << "HDJ2534.dll - load error!" << endl;
return 0;
}

//Open Device
callPassThruOpen();

//Connect Channel_1 CAN 125000bps

Page 15 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

callPassThruConnect();

//Soft Reset the module
callPassThruReset();

//Re-Open Device
callPassThruOpen();

//Connect Channel_1 CAN 125000bps
callPassThruConnect();

//Write a single message
callPassThruWriteMsgs();

//Set Read Message filter 0
callPassThruStartMsgFilter();

//Read one single message
callPassThruReadMsgs();

//Delete Read Message Filter 0
callPassThruStartMsgFilter();

//Disconnect Channel_1
callPassThruDisconnect();

//Close Device
callPassThruClose();

freeLib();

return 1;

}

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 16 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

a) J2534_ERROR_CODE J2534::PassThruClose

(

unsigned long

DeviceID

)

[in]

DeviceID

DeviceID returned from PassThruOpen.

b) J2534_ERROR_CODE J2534::PassThruConnect

(

unsigned long

DeviceID,

J2534_PROTOCOL

ProtocolID,

unsigned long

Flags,

unsigned long

BaudRate,

unsigned long *

pChannelID

)

[in]

DeviceID

Device ID returned from PassThruOpen.

[in]

ProtocolID

Protocol ID.

[in]

Flags

Connection flags.

[in]

BaudRate

Initial baud rate.

[out]

*pChannelID

Pointer to location for the channel ID that is assigned by the
library.

4. Appendix

This function is used to close the connection to a Pass-Thru Device. All periodic messages
will be stopped, filters will be cleared, and all pins will return to their default state (see
Section 6.8). This function must be called before an application exits. The libray can use
this function to de-allocate data structures and deactivate any device drivers. If the
function is successful, a value of STATUS_NOERROR is returned. After this call, all active
protocols will be disconnected, Channel IDs will no longer be valid, and any function call
other than PassThruOpen will result in the error ERR_INVALID_DEVICE_ID being
returned (with the exception of PassThruGetLastError).

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

This function is used to establish a logical connection with a protocol channel on the
specified SAE J2534 device. After this function is called, the value pointed to by
pChannelID is used as the logical identifier for the combination of Device ID and Protocol
ID. If the function is successful, a value of STATUS_NOERROR is returned and a valid
channel ID will be placed in pChannelID. All future interactions with the protocol channel
will be done using the pChannelID. Note that the interface will block all received
messages on this channel until a filter is set.

Parameters:

Returns:

Connect request status, see function return codes in hdj2534.h.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 17 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

c) J2534_ERROR_CODE J2534::PassThruDisconne

ct

(

unsigned
long

ChannelI
D

)

[in]

ChannelID

The channel ID assigned by the PassThruConnect function.

d) J2534_ERROR_CODE J2534::PassThruGetLastError

(

char
*

pErrorDescriptio
n

)

[in]

*pErrorDescription

Pointer to buffer for error description string.

e) J2534_ERROR_CODE J2534::PassThruGetStat

us

(

unsigned long

ChannelID

,

unsigned long
*

Status

)

[in]

ChannelID

Channel ID returned from PassThruOpen.

[out]

*Status

Pointer to location for the Status to set to.

This function is used to terminate a logical connection with a protocol channel. If the
function is successful, a value of STATUS_NOERROR is returned. After this call, all filters
associated with the channel will be cleared, all periodic messages associated with the
channel will be stopped, the associated pins will return to their default state (see Section

6.8) and the Channel ID will no longer be valid.

Parameters:

Returns:

Status Disconnect request status, see function return codes in hdj2534.h.

This function returns the text string description for an error detected during the last
function call (except PassThruGetLastError). The error string must be retrieved before
calling any other function. The buffer pointed to by pErrorDescription is allocated by the
application and must be at least eighty (80) characters.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

This method was added to give the user-application a way to read the status of the CAN­Gateway and maps to the CAN-Status Register in the LPC17xx. This works for RAWCAN
only.

Parameters:

Returns:

Connect request status.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 18 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

f) J2534_ERROR_CODE J2534::PassThruIoctl

(

unsigned long

ChannelID,

J2534_IOCTL

IoctlID,

void *

pInput,

void *

pOutput

)

g) J2534_ERROR_CODE J2534::PassThruOpen

(

void *

pName,

unsigned long *

pDeviceID

)

[in]

*pName

Used for selecting which device to use (reserved
in J2534 spec).

[out]

*pDeviceID

Pointer to location for the device ID that is assigned by the
library.

This function is used to read and write all the protocol hardware and software
configuration parameters. If the function is successful, a value of STATUS_NOERROR is
returned. The structures pointed to by pInput and pOutput are determined by the
IoctlID. param[in] ChannelID The channel ID assigned by the PassThruConnect function,
except in designated Ioctls where the device ID is passed instead. (!!!) param[in] IoctlID
Ioctl ID. param[in,out] *pInput Pointer to input structure. param[in,out] *pOutput
Pointer to output structure.

Returns:

Status, see function return codes in hdj2534.h

This function is used to establish a connection and initialize the Pass-Thru Device. This
function must be called one time before any other function with the exception of
PassThruGetLastError. Any function called before a successful call to PassThruOpen must
return ERR_INVALID_DEVICE_ID. If the function is successful, a value of
STATUS_NOERROR is returned. The Device ID returned is used as a handle to the
initialized SAE J2534 device.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 19 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

h) J2534_ERROR_CODE J2534::PassThruReadMsgs

(

unsigned long

channelID,

PASSTHRU_MSG

*

pMsg,

unsigned long *

pNumMsgs

,

unsigned long

timeout

)

[in]

channelID

The channel ID assigned by the PassThruConnect function.

[in]

*pMsg

Pointer to start of messages.

[in]

*pNumMsgs

Pointer to location where number of messages to read is
specified.

[in]

timeout

Read timeout (in milliseconds). If a value of 0 is specified the
function retrieves up to pNumMsgs messages and returns
immediately. Otherwise, the API will not return until the
Timeout has expired, an error has occurred, or the desired
number of messages have been read. If the number of
messages requested have been read, the function shall not
return ERR_TIMEOUT, even if the timeout value is zero.

[out]

*pMsg

Pointer to message structure(s).

This function reads messages and indications from the receive buffer. All messages and
indications shall be read in the order that they occurred on the bus. If a transmit
message generated a loopback message and TxDone indication, the TxDone indication
shall always be queued first. Except for loopback messages and indications, no messages
shall be queued for reception without matching a PASS_FILTER (for non-ISO 15765) or
FLOW_CONTROL filter (for ISO 15765). On ISO 15765, PCI bytes are transparently
removed by the API. If the function is successful, a value of STATUS_NOERROR is
returned.

Parameters:

Returns:

Connect request status, see function return codes in hdj2534.h

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 20 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

i) J2534_ERROR_CODE J2534::PassThruReadVersion

(

unsigned
long

DeviceID,

char *

pFirmwareVer
sion,

char *

pLibVersion,

char *

pApiVersion

)

[in]

DeviceID

Device ID returned from PassThruOpen.

[out]

*pFirmwareVersion

Pointer to Firmware version string.

[out]

*pLibVersion

Pointer to library version string.

[out]

*pApiVersion

Pointer to API version string in YY. MM format.

j) J2534_ERROR_CODE J2534::PassThruSetProgramm

ingVoltage

(

unsigned
long

DeviceID,

unsigned
long

PinNumb
er,

unsigned
long

Voltage

)

[in]

DeviceID

Device ID returned from PassThruOpen.

[in]

PinNumber

The pin on which the programming voltage will be set.

[in]

Voltage

The voltage (in millivolts) to be set.

This function returns the version strings associated with the library. If the function is
successful, a value of STATUS_NOERROR is returned. A buffer of at least eighty (80)
characters must be allocated for each pointer by the application.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

Note:

THIS FUNCTION IS NOT IMPLEMENTED. It is only provided to comply with
the J2534 specification.

This function sets a single programming voltage on a single specific pin.

Parameters:

Returns:

Status (Always ERR_NOT_SUPPORTED), see function return codes in hdj2534.h.

Note:

THIS FUNCTION IS NOT IMPLEMENTED. It is only provided to comply with
the J2534 specification.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 21 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

k) J2534_ERROR_CODE J2534::PassThruS

tartMsgFilter

(

unsigned long

ChannelI
D,

J2534_FILTER

FilterType

,

PASSTHRU_MSG *

pMaskMsg

,

PASSTHRU_MSG *

pPattern
Msg,

PASSTHRU_M
SG *

pFlowControlMsg,

unsigned long
*

pFilterID

)

[in]

ChannelID

The channel ID assigned by the PassThruConnect
function.

[in]

FilterType

Designates filter type (PASS, BLOCK, FLOW_CONTROL).

[in]

*pMaskMsg

Pointer to the Mask message.

[in]

*pPatternMsg

Pointer to the Pattern message.

[in]

*pFlowControlMsg

Pointer to the Flow Control message (ISO 15765 only).

[in]

*pFilterID

Pointer to location for the filter ID that is assigned by
the library.

This function starts filtering of incoming messages. If the function is successful, a value
of STATUS_NOERROR is returned. A minimum of ten message filters shall be supported
by the interface for each supported protocol. PassThruDisconnect shall delete all message
filters on that channel. PassThruClose shall delete all filters on all channels for the device.
Pattern and Mask messages shall follow the protocol formats specified in Section 8.
However, only the first twelve (12) bytes, including header or CAN ID, are used by the
filter. ERR_INVALID_MSG shall be returned if the filter length exceeds 12. Note that this
function does not clear any messages that may have been received and queued before
the filter was set.

Parameters:

Returns:

Status, see function return codes in hdj2534.h

Note:

MsgFilter has to be defined in order to receive messages.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 22 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

l) J2534_ERROR_CODE J2534::PassThruStartPer

iodicMsg

(

unsigned long

ChannelID,

PASSTHRU_MS
G *

pMsg,

unsigned long
*

pMsgID,

unsigned long

TimeInterv
al

)

[in]

ChannelID

The channel ID assigned by the PassThruConnect function.

[in]

*pMsg

Pointer to message structure(s).

[in]

*pMsgID

Pointer to location for the message ID that is assigned by the
library.

[in]

TimeInterval

Time interval between the start of successive transmissions of
this message, in milliseconds. The valid range is 5-65535
milliseconds.

m) J2534_ERROR_CODE J2534::PassThruStopMsgFilter

(

unsigned
long

ChannelID,

unsigned
long

FilterID

)

[in]

ChannelID

The channel ID assigned by the PassThruConnect function.

[in]

FilterID

Filter ID that is assigned by the PassThruStartMsgFilter function.

This function will immediately queue the specified message for transmission, and repeat
at the specified interval. Periodic messages are limited in length to a single frame
message of 12 bytes or less, including header or CAN ID. If the function is successful, a
value of STATUS_NOERROR is returned. The Pass-Thru device must support a minimum
of ten periodic messages.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

This function removes the specified filter. If the function is successful, a value of
STATUS_NOERROR is returned. After this call the FilterID will be invalid.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 23 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

n) J2534_ERROR_CODE J2534::PassThruStopPeriodi

cMsg

(

unsigned
long

ChannelI
D,

unsigned
long

MsgID

)

[in]

ChannelID

The channel ID assigned by the PassThruConnect function.

[in]

MsgID

Message ID that is assigned by the PassThruStartPeriodicMsg
function.

This function stops the specified periodic message. If the function is successful, a value
of STATUS_NOERROR is returned. After this call the MsgID will be invalid.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 24 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

o) J2534_ERROR_CODE J2534::PassThruWriteMsg

s

(

unsigned long

ChannelID,

PASSTHRU_MS
G *

pMsg,

unsigned long
*

pNumMsgs

,

unsigned long

Timeout

)

[in]

ChannelID

The channel ID assigned by the PassThruConnect function.

[in]

*pMsg

Pointer to message structure(s).

[in]

*pNumMsgs

Pointer to location where number of messages to write is
specified.

[in]

Timeout

Write timeout (in milliseconds). When a value of 0 is
specified, the function queues as many of the specified
messages as possible and returns immediately. When a value
greater than 0 is specified, the function will block until the
Timeout has expired, an error has occurred, or the desired
number of messages have been transmitted on the vehicle
network. Even if the device can buffer only one packet at a
time, this function shall be able to send an arbitrary number
of packets if a Timeout value is supplied. Since the function
returns early if all the messages have been sent, there is
normally no penalty for having a large timeout (several
seconds). If the number of messages requested have been
written, the function shall not return ERR_TIMEOUT, even if
the timeout value is zero.

[out]

*pNumMsgs

On return will contain the actual number of messages that
were transmitted (when Timeout is nonzero) or placed in the
transmit queue (when Timeout is zero).

This function is used to send messages. The messages are placed in the buffer and sent
in the order they were received. Only one message per protocol can be in transmission at
a time (with one exception - see PassThruStartPeriodicMsg). If the function is successful,
a value of STATUS_NOERROR is returned. Specifying a non-zero Timeout performs a
blocking write. When using blocking writes, this function does not return until all
messages are successfully sent on the vehicle network, or the timeout has expired or an
error occurs.

Parameters:

Returns:

Status, see function return codes in hdj2534.h.

DOC101357-1_ - rev 2 – 2013-09-23 - Created by:6644

Page 25 of 25

Hatteland Display AS, Åmsosen, N-5578 Nedre Vats, Norway

Tel: [phone] - [e-mail] - www.hatteland-display.com

HD CAN Module Programmer’s Guide (Windows)

All intellectual properties belongs to Hatteland Display AS

p) J2534_ERROR_CODE J2534::PassThruReset( void )

This function resets gateway.

Parameters

Returns

Status, see function return codes in hdj2534.h.