Kvaser CANLIB: J1587
Data Structures | Defines | Typedefs | Functions

J1587

Data Structures

struct  J1587MessageInfo

Defines

#define j1587INVALID_HANDLE   ((J1587Handle)(-1))
#define J1587LIB_VERSION   1

Typedefs

typedef int J1587Handle

Functions

J1587Status j1587Close (J1587Handle h)
J1587Status j1587GetFirmwareVersion (J1587Handle h, unsigned char *bootVerMajor, unsigned char *bootVerMinor, unsigned char *bootVerBuild, unsigned char *appVerMajor, unsigned char *appVerMinor, unsigned char *appVerBuild)
J1587Status j1587SetBitrate (J1587Handle h, unsigned int bps)
J1587Status j1587BusOn (J1587Handle h)
J1587Status j1587BusOff (J1587Handle h)
unsigned long j1587ReadTimer (J1587Handle h)
J1587Status j1587WriteMessageWait (J1587Handle h, const void *msg, unsigned int length, unsigned int priority, DWORD timeout)
J1587Status j1587ReadMessageWait (J1587Handle h, void *msg, unsigned int *msgLength, J1587MessageInfo *msgInfo, DWORD timeout)
J1587Status j1587WriteSync (J1587Handle h, J1587MessageInfo *msgInfo, DWORD timeout)
J1587Status j1587Configure (J1587Handle h, unsigned int flags)
J1587Status j1587GetCanHandle (J1587Handle h, unsigned int *canHandle)

Linx tranceiver types


#define canTRANSCEIVER_TYPE_LINX_LIN   64
#define canTRANSCEIVER_TYPE_LINX_J1708   66
#define canTRANSCEIVER_TYPE_LINX_K   68
#define canTRANSCEIVER_TYPE_LINX_SWC   70
#define canTRANSCEIVER_TYPE_LINX_LS   72

Operation modes


#define EEPROM_OP_MODE_NONE   0x00
#define EEPROM_OP_MODE_J1587_NORMAL   0x01
#define EEPROM_OP_MODE_J1587_NODE   0x02

Flags for J1587MessageInfo


#define j1587FLAG_CHECKSUM   0x80
#define j1587FLAG_FRAMEDELAY   0x40
#define j1587FLAG_BYTEDELAY   0x20
#define j1587FLAG_STOPBIT   0x10
#define j1587FLAG_OVERRUN   0x08

Return codes from the J1587lib functions


enum  J1587Status {
  j1587OK = 0,
  j1587ERR_NOMSG = -1,
  j1587ERR_NOTRUNNING = -3,
  j1587ERR_RUNNING = -4,
  j1587ERR_NORMALONLY = -5,
  j1587ERR_NODEONLY = -6,
  j1587ERR_PARAM = -7,
  j1587ERR_NOTFOUND = -8,
  j1587ERR_NOMEM = -9,
  j1587ERR_NOCHANNELS = -10,
  j1587ERR_TIMEOUT = -11,
  j1587ERR_NOTINITIALIZED = -12,
  j1587ERR_NOHANDLES = -13,
  j1587ERR_INVHANDLE = -14,
  j1587ERR_CANERROR = -15,
  j1587ERR_ERRRESP = -16,
  j1587ERR_WRONGRESP = -17,
  j1587ERR_DRIVER = -18,
  j1587ERR_DRIVERFAILED = -19,
  j1587ERR_NOCARD = -20,
  j1587ERR_LICENSE = -21,
  j1587ERR_INTERNAL = -22,
  j1587ERR_NO_ACCESS = -23,
  j1587ERR_VERSION = -24
}

J1587MessageInfo

In certain J1587 bus API calls, the following structure is used to provide more information about the J1587 messages.
void j1587InitializeLibrary (void)
J1587Handle j1587OpenChannel (int channel, int flags)

Flags for j1587OpenChannel()


#define J1587_NORMAL   1
#define J1587_NODE   2
#define J1587_READ   4
#define J1587_WRITE   8

Flags for j1587Configure()


#define J1587_INTER_CHAR_DELAY_MASK   0x0f
#define J1587_REPORT_BAD_CHECKSUM   0x10
#define J1587_REPORT_FRAME_DELAY   0x20
#define J1587_REPORT_CHAR_DELAY   0x40

Define Documentation

#define canTRANSCEIVER_TYPE_LINX_J1708   66
#define canTRANSCEIVER_TYPE_LINX_K   68
#define canTRANSCEIVER_TYPE_LINX_LIN   64
#define canTRANSCEIVER_TYPE_LINX_LS   72
#define canTRANSCEIVER_TYPE_LINX_SWC   70
#define EEPROM_OP_MODE_J1587_NODE   0x02
#define EEPROM_OP_MODE_J1587_NORMAL   0x01
#define EEPROM_OP_MODE_NONE   0x00
#define J1587_INTER_CHAR_DELAY_MASK   0x0f

Inter character delay mask.

#define J1587_NODE   2
#define J1587_NORMAL   1
Examples:
j1587example.c.
#define J1587_READ   4
Examples:
j1587example.c.
#define J1587_REPORT_BAD_CHECKSUM   0x10

Default off.

Examples:
j1587example.c.
#define J1587_REPORT_CHAR_DELAY   0x40

Default off.

Examples:
j1587example.c.
#define J1587_REPORT_FRAME_DELAY   0x20

Default off.

Examples:
j1587example.c.
#define J1587_WRITE   8
Examples:
j1587example.c.
#define j1587FLAG_BYTEDELAY   0x20
#define j1587FLAG_CHECKSUM   0x80
#define j1587FLAG_FRAMEDELAY   0x40
#define j1587FLAG_OVERRUN   0x08
#define j1587FLAG_STOPBIT   0x10
#define j1587INVALID_HANDLE   ((J1587Handle)(-1))

Invalid J1587 handle

#define J1587LIB_VERSION   1

J1587 library version definition


Typedef Documentation

typedef int J1587Handle

J1587 handle


Enumeration Type Documentation

Enumerator:
j1587OK 

OK - no error.

j1587ERR_NOMSG 

No messages available.

j1587ERR_NOTRUNNING 
j1587ERR_RUNNING 
j1587ERR_NORMALONLY 
j1587ERR_NODEONLY 
j1587ERR_PARAM 

Error in parameter.

j1587ERR_NOTFOUND 

Specified hw not found.

j1587ERR_NOMEM 

Out of memory.

j1587ERR_NOCHANNELS 

No channels avaliable.

j1587ERR_TIMEOUT 

Timeout occurred.

j1587ERR_NOTINITIALIZED 

Library not initialized.

j1587ERR_NOHANDLES 

Can't get handle.

j1587ERR_INVHANDLE 

Handle is invalid.

j1587ERR_CANERROR 
j1587ERR_ERRRESP 

There was an error response from the J1587 interface.

j1587ERR_WRONGRESP 

The J1587 interface response wasn't the expected one.

j1587ERR_DRIVER 

CAN driver type not supported.

j1587ERR_DRIVERFAILED 

DeviceIOControl failed; use Win32 GetLastError()

j1587ERR_NOCARD 

The card was removed or not inserted.

j1587ERR_LICENSE 

The license is not valid.

j1587ERR_INTERNAL 

Internal error in the driver.

j1587ERR_NO_ACCESS 

Access denied.

j1587ERR_VERSION 

Function not supported in this version.


Function Documentation

J1587Status j1587BusOff ( J1587Handle  h)

This function deactivates the J1587 interface. It will be reset clearing any settings such as J1587 data buffers active.

Parameters:
[in]hA handle to an open J1587 channel.
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.
J1587Status j1587BusOn ( J1587Handle  h)

This function activates the J1587 interface.

Note:
It will be reset, so any setups done earlier will be lost.
Parameters:
[in]hA handle to an open J1587 channel.
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.
J1587Status j1587Close ( J1587Handle  h)

Closes an open handle to a J1587 channel. The handle becomes invalid and can not be used in subsequent calls to the J1587 functions.

Parameters:
[in]hA handle to an open J1587 channel.
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
See also:
j1587OpenChannel()
Examples:
j1587example.c.
J1587Status j1587Configure ( J1587Handle  h,
unsigned int  flags 
)

With this function, it is possible to change settings on a J1587 Interface that is on-bus. When going on-bus, the bitrate and the flag values J1587_REPORT_xxx are set to the default value (either as hard-coded in the firmware, or as stored in the non-volatile memory of the J1587 Interface).

Note:
The J1587 Interface must be on bus for this command to work.
Parameters:
[in]hA handle to an open J1587 channel.
[in]flagsFlags, see J1587_REPORT_xxx
Returns:
j1587OK (zero) if all writes are done
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.
J1587Status j1587GetCanHandle ( J1587Handle  h,
unsigned int *  canHandle 
)

Return the CAN handle given an open J1587 handle

Parameters:
[in]hA handle to an open J1587 channel.
[out]canHandleA pointer to an integer where the CAN handle will be stored.
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
J1587Status j1587GetFirmwareVersion ( J1587Handle  h,
unsigned char *  bootVerMajor,
unsigned char *  bootVerMinor,
unsigned char *  bootVerBuild,
unsigned char *  appVerMajor,
unsigned char *  appVerMinor,
unsigned char *  appVerBuild 
)

This function retrieves the firmware version from the J1587 interface.

Note:
The version numbers aren't valid until j1587BusOn() has been called.
The firmware in the J1587 interface is divided into two parts, the boot code and the application. The boot code is used only when reprogramming (reflashing) the J1597 interface. The application handles all J1587 communication.
Version numbers are, since the precambric era, divided into a major version number, a minor version number and a build number. These are usually written like, for example, 3.2.12. Here the major number is 3, the minor number 2 and the build number 12.
Parameters:
[in]hA handle to an open J1587 channel.
[out]bootVerMajorA pointer to a byte where the major version number of the boot code is stored.
[out]bootVerMinorA pointer to a byte where the minor version number of the boot code is stored.
[out]bootVerBuildA pointer to a byte where the build number of the boot code is stored.
[out]appVerMajorA pointer to a byte where the major version number of the application code is stored.
[out]appVerMinorA pointer to a byte where the minor version number of the application code is stored.
[out]appVerBuildA pointer to a byte where the build number of the application is stored.
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.
void j1587InitializeLibrary ( void  )

To be called before the library is used.

Examples:
j1587example.c.
J1587Handle j1587OpenChannel ( int  channel,
int  flags 
)

Open a channel to a J1587 interface.

Note:
The J1587 cable must be powered.

The channel number is the same that is used by canOpenChannel() to access the LAPcan channel.

Parameters:
[in]channelThe number of the channel. This is the same as used by canOpenChannel() to access the LAPcan channel.
[in]flagsFlags of type J1587_xxx
Returns:
If the call succeeds, a handle to the opened channel is returned. The handle is an integer greater than or equal to zero.
If the call fails, the return value is a negative integer indicating an error code. See j1587ERR_xxx for a list of possible error codes.
See also:
j1587Close()
Examples:
j1587example.c.
J1587Status j1587ReadMessageWait ( J1587Handle  h,
void *  msg,
unsigned int *  msgLength,
J1587MessageInfo msgInfo,
DWORD  timeout 
)

Read a J1587 message.

Parameters:
[in]hA handle to an open J1587 channel.
[out]msgA pointer to a buffer where the J1587 message will be stored.
[out]msgLengthA pointer to an integer where the length of the received J1587 message will be stored.
[out]msgInfoA pointer a J1587MessageInfo structure where the message information will be stored.
[in]timeoutTimes out after timeout milliseconds
Returns:
j1587OK (zero) if success
j1587ERR_NOMSG if nothing is received
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.
unsigned long j1587ReadTimer ( J1587Handle  h)

Return the current timer value (used for timestamps)

Note:
For convenience, this call returns the timer value instead of passing it in a parameter. This means that if the call fails, it will still return a value (which then is the error code, type casted to a long unsigned integer - e.g. 0xFFFFFFF2 for j1587ERR_INVHANDLE. Watch out.
Parameters:
[in]hA handle to an open J1587 channel.
Returns:
If the call succeeds, the present timer value is returned.
Examples:
j1587example.c.
J1587Status j1587SetBitrate ( J1587Handle  h,
unsigned int  bps 
)

This function sets the bit rate

Note:
The J1587 Interface should not be on bus.
Parameters:
[in]hA handle to an open J1587 channel.
[in]bpsBit rate in bits per second.
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.
J1587Status j1587WriteMessageWait ( J1587Handle  h,
const void *  msg,
unsigned int  length,
unsigned int  priority,
DWORD  timeout 
)

Write a J1587 message. Times out after timeout ms.

Parameters:
[in]hA handle to an open J1587 channel.
[in]msgA pointer to a buffer containing the J1587 message.
[in]lengthLength of message, max 0xFFF
[in]priorityPriority of message, max 0xFF
[in]timeoutTimes out after timeout milliseconds
Returns:
j1587OK (zero) if success
j1587ERR_xxx (negative) if failure
J1587Status j1587WriteSync ( J1587Handle  h,
J1587MessageInfo msgInfo,
DWORD  timeout 
)

Call this function to make sure all messages transmitted to the J1587 Interface have been received by it.

When messages are transmitted to the J1587 Interface, they are queued by Windows before appearing on the CAN bus.

Parameters:
[in]hA handle to an open J1587 channel.
[out]msgInfoA pointer a J1587MessageInfo structure where the message information will be stored.
[in]timeoutTimes out after timeout milliseconds
Returns:
j1587OK (zero) if all writes are done
j1587ERR_xxx (negative) if failure
Examples:
j1587example.c.