General

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)
 

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)
 

Detailed Description

Function Documentation

◆ j1587BusOff()

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:
example/c/j1587/j1587example.c.

◆ j1587BusOn()

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:
example/c/j1587/j1587example.c.

◆ j1587Close()

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:
example/c/j1587/j1587example.c.

◆ j1587Configure()

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:
example/c/j1587/j1587example.c.

◆ j1587GetCanHandle()

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

◆ j1587GetFirmwareVersion()

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:
example/c/j1587/j1587example.c.

◆ j1587InitializeLibrary()

void j1587InitializeLibrary ( void  )

To be called before the library is used.

Examples:
example/c/j1587/j1587example.c.

◆ j1587OpenChannel()

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:
example/c/j1587/j1587example.c.

◆ j1587ReadMessageWait()

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:
example/c/j1587/j1587example.c.

◆ j1587ReadTimer()

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:
example/c/j1587/j1587example.c.

◆ j1587SetBitrate()

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:
example/c/j1587/j1587example.c.

◆ j1587WriteMessageWait()

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

◆ j1587WriteSync()

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:
example/c/j1587/j1587example.c.