jCOM Series by Copperhill Technologies

Embedded Network Solutions

SAE J1939 – NMEA 2000 – ISOBUS – MilCAN – CAN

Contact Us: [email protected]

For more information see http://copperhilltech.com

JCOM.J1939 PROTOCOL & PROGRAMMING INTERFACE

The jCOM.J1939 gateway series by Copperhill Technologies represent high-
performance, low-latency vehicle network adapters. They allow any host device with a
serial COM port (USB or UART) to monitor SAE J1939 data traffic and communicate with
the SAE J1939 vehicle network. The gateways support the full SAE J1939 protocol
according to J1939/81 Network Management (Address Claiming), J1939/21 Transport
Protocol (TP), and J1939/16 (Automatic CAN baud rate detection).

The jCOM.J1939 Gateway Protocol is designed to establish a data exchange between a

jCOM.J1939 Series gateway and a host system (e.g. a PC or embedded system such as
the Raspberry Pi) per means of serial communication (UART, USB). The protocol enables
the host system to take advantage of the gateway’s capabilities by providing a set of
commands from the host and responses from the gateway.

JCOM.J1939 GATEWAY OPERATING MODES

The jCOM.J1939 gateways supports two operating modes to cover all possible scenarios.
The operating mode can be set by the host system per command through the serial port
(USB or UART) as described in the next chapter.

The modes are:

1. Listen-Only (Default): This mode supports a mere J1939 data-monitoring mode,

which does not require the use of a NAME and source address, i.e. there is no
address claim process.
2. Communication: This mode allows full communication, i.e. bidirectional data
transfer, between the host system and the J1939 vehicle network.

A jCOM.J1939 gateway works per default as a mere monitoring device in Listen-Only

mode, however, the gateway will, also per default, not report any data unless the host
system (e.g. a PC under Windows/Linux) sets the corresponding filters (ADDFILTER
command).
A full communication, i.e. bidirectional data transfer, between the host system and the
J1939 vehicle network is only possible after the host system initiates the J1939 Address
Claim process by sending the corresponding command (SETPARAM).

All operating modes allow the reception of up to 1785 bytes per message, while the
Communication operating mode also allows the transmission of up to 1785 bytes per
message (BAM or RTS/CTS Session).

The Communication operating mode engages the full Address Claim procedure,
requiring a NAME, a preferred source address (SA), and an optional address range (in
case the preferred SA is already taken).

The transmission of J1939 messages in the Communication operating mode is always

“real-time,” i.e. the message is being transmitted as soon as possible (as soon as the
gateway proceeds during the bus arbitration process).

START-UP SEQUENCE
The start-up sequences for each mode are:

Listen-Only:
1. Send RESET command, which also initializes the CAN baud rate (250/500 kbps).
2. Set all filters (ADDFILTER command).
3. Operation starts with setting the first filter.

Communication:
1. Send RESET command, which also initializes the CAN baud rate (250/500 kbps).
2. Initiate Address Claim Process and set operating mode using the SETPARAM or
SETPARAM1 command.
3. When using the SETPARAM1 command, the gateway responds with REPSTATUS
message.
4. After successful address claim (check status per REPSTATUS message), data
transmission is enabled.
5. Set all filters (ADDFILTER command).
6. Receiving messages is enabled with setting the first filter.

SERIAL COMMUNICATIONS PROTOCOL

This chapter describes the message framing protocol used to define the start and body
of messages sent between host device and the jCOM.J1939 gateway.

2
MESSAGE FORMAT
The jCOM.J1939 protocol defines two special tokens, START and ESC. START has the
value of 192 decimal and ESC has the value of 219 decimal.

Data is sent to and from the jCOM.J1939 gateway using the industry standard method of
byte stuffing. Byte stuffing is the process of inserting additional tokens when the START
or ESC tokens are part of the data field.

All messages start with a START token, and due to byte stuffing, a START token can
never appear in any other part of the message. If the value of 192 is contained in the
message length, data field, or checksum, an ESC token is inserted into the data stream
followed by a 220, this indicates a value of 192. If an ESC token appears in the message
length, data field, or checksum, an ESC token is inserted into the stream followed by a
221, this indicates a value of 219.

All messages must be byte stuffed, following the START token, by the transmitter and
unstuffed by the receiver.

Code Dec / Hex Description

START 192 / 0xC0 Start of Message
ESC 219 / 0xDB Stuffing Byte
START_STUFF 220 / 0xDC Stuffing Byte
ESC_STUFF 221 / 0xDD Stuffing Byte
DATA_START ESC+START_STUFF Data = 219, 220 / 0xDB, 0xDC
DATA_ESC ESC+ESC_STUFF Data = 219, 221 / 0xDB, 0xDD

To send a packet, the transmitting device starts by sending a START character followed
by the size of the data to follow, along with the data and the checksum of the packet.

The message length is a 2-byte field (MSB first, followed by LSB) equal to the size of the
data field plus checksum, both before byte stuffing.

The checksum is a 2’s complement checksum over the length and data fields and is
calculated before byte stuffing has been added.

3
WHAT IS A 2’S COMPLEMENT CHECKSUM?
A checksum is a technique to check data for transmission errors or tampering. If the last
few bytes are the sum of all the preceding bytes, then any errors are likely to be
detected.

In this case, the checksum is the sum of all bytes between the data length field (MSB)
and the last byte of the actual data field, ignoring any carry, meaning the checksum is
always 8 bits long (0 to 255).

A one’s complement is just a complement: ~x

A two’s complement is a complement and increment, ignoring carry: (~x)+1

MESSAGES
This chapter describes the commands sent to and received from the gateway.

Note: All message definitions are documented in their unstuffed representation. All
highlighted sections represent the data field.

Every message is part of the data field, and it starts with a message identifier. This is an
eight-bit value that tells the receiver what type of message follows. This is followed by
one or more additional data field(s), depending on the message. The message
identifiers, data fields, responses, etc. are documented for each message in the
following chapters.

The available messages and their message IDs are:

Message ID Meaning Source Acknowledge

ACK 0 Acknowledgement Gateway -
ADDFILTER 1 Add Filter Host ACK
DELFILTER 2 Delete Filter Host ACK

4
TXDATA 3 Transmit Data Host ACK
RXDATA 4 Receive Data Gateway -
RESET 5 Reset jCOM.J1939.USB Host ACK
HEART 6 Heartbeat Gateway -
SETPARAM 7 Set Protocol Parameters Host ACK
REQINFO 8 Request Information Host REPSTATUS or
RXDATA or
VERSION
REPSTATUS 9 Report Protocol Status Gateway -
FLASH 10 Starts flash programmer Host ACK
SETACK 11 Set Acknowledgement Host ACK
SETHEART 12 Set Heartbeat Frequency Host ACK
VERSION 13 Report HW/SW Version Gateway -
SETPARAM1 14 Set Protocol Parameters Host ACK
With REPSTATUS response
SETMSGMODE 15 Set Message Mode Host ACK
TXDATAL 16 Transmit Data Loopback Host ACK
TXDATAP 17 Periodic Data Transmission Host ACK
TXDATAPL 18 TXDATAP with Loopback Host ACK

Note: This list of messages is sorted by message ID. The original protocol included only
the first 10 messages and further messages were added over time. In order to maintain
a strict backwards compatibility, the function of a message, once established, will
remain unchanged. Any additional or modified functionality is accomplished through
new messages (as an example, see the original TXDATA and the added TXDATAL
messages).

ADDITIONAL DUO MESSAGE IDS

The following message IDs were added to support our dual-port J1939 gateways. They
are identical in functionality to the original messages but their ID was increased by 128
(0x80) to indicate access to the second J1939 port.

Message ID Meaning Source Acknowledge

ADDFILTER2 129 Add Filter Host ACK
DELFILTER2 130 Delete Filter Host ACK
TXDATAX2 131 Transmit Data Host ACK
RXDATA2 132 Receive Data Gateway -
SETPARAM2 135 Set Protocol Parameters Host ACK
REQINFO2 136 Request Information Host REPSTATUS or
RXDATA or
VERSION
REPSTATUS2 137 Report Protocol Status Gateway -
SETPARAM12 142 Set Protocol Parameters Host ACK

5
 With REPSTATUS response
SETMSGMODE2 143 Set Message Mode Host ACK
TXDATAL2 144 Transmit Data Loopback Host ACK
TXDATAP2 145 Periodic Data Transmission Host ACK
TXDATAPL2 146 TXDATAP with Loopback Host ACK

Note: These messages are only implemented in our dual-port gateways. The single-port
gateways will not respond to them.

ACK – Acknowledgment
This message is sent by the jCOM.J1939to acknowledge the correct receipt of a message
from the host system. ACK will not be transmitted in cases where the checksum is wrong
or byte-stuffing errors were detected.

Note:
• The ACK message can be suppressed through the SETACK message.

Message Identifier: 0
Total Length: 6 bytes
Response: -

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 3
3 MSG_ID_ACK 0
4 Message Id of acknowledged message xx
5 Checksum xx

ADDFILTER – Add Filter PGN

This message adds a PGN to the acceptance filter. The jCOM.J1939 gateway allows up to
100 message filters; in the DUO version 50 message filters are supported per port. Set
the PGN to 0x100000 to allow all data without filtering; disable the feature by deleting
the filter (DELFILTER command) using the same PGN.

Note:
• The jCOM.J1939 gateway will, per default, not pass on any data messages unless
their associated PGN is set (ADDFILTER command).

6
 • Setting filters referring to PGNs used for Address Claim or Network Management
will be ignored, i.e. the gateway reports only data and request PGNs.
• To enable SAE J1939 request messages (PGN = 0xEAxx), it is sufficient to use the
base PGN 0xEA00 (59904) or any PGN in the range from 0xEA00 to 0xEAFF,
which will enable the entire range.

Message Identifier: 1
Total Length: 8 bytes
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 5
3 MSG_ID_FA 1
4 PGN MSB xx
5 PGN 2ND xx
6 PGN LSB xx
7 CHKSUM xx

DELFILTER – Delete Filter PGN

This message deletes a PGN from the acceptance filter. Set the PGN to 0x100000 to
disallow the reception of all data.

Note:
• The gateway will, per default, not pass on any data messages unless their
associated PGN is set (ADDFILTER command).

Message Identifier: 2
Total Length: 8 bytes
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 5
3 MSG_ID_FA 2
4 PGN MSB xx
5 PGN 2ND xx
6 PGN LSB xx
7 CHKSUM xx

7
TXDATA – Transmit Data
This message schedules a J1939 message for transmission. The message will be sent as
soon as the J1939 network allows.

Note:
• The gateway will not transmit any data during the Address Claim process (applies
only to the Communication operating mode), which can last up to several
hundreds of milliseconds.
• A J1939 message can be between 0 and 1785 bytes long. If a message is longer
than 8 bytes, the jCOM.J1939 gateway will, depending on the destination
address, manage the transmission per broadcast (BAM) or peer-to-peer
(RTS/CTS) session.
• The jCOM.J1939 gateway will allow you the use of a random source address,
provided that the address claim process was finished successfully. It is highly
recommended using the negotiated source address (obtained through the
REPSTATUS message). Nevertheless, this feature is provided for maximum
flexibility.

Message Identifier: 3
Total Length: Variable (19 with 8 data bytes)
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB xx
2 Length LSB xx
3 MSG_ID_TX 3
4 PGN MSB xx
5 PGN 2ND xx
6 PGN LSB xx
7 Destination Address xx
8 Source Address xx
9 Priority 0…7
10 Data Field Start xx
:
:
nn CHKSUM xx

TXDATAL – Transmit Data With Loopback

This message is designed (and handles data transmission exactly) like the regular
TXDATA message. However, when the gateway receives the TXDATAL message, the data

8
will be reflected back to the host system (which is a mandatory feature for gateway
applications).

Message Identifier: 16
Total Length: Variable (19 with 8 data bytes)
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB xx
2 Length LSB xx
3 MSG_ID_TX 16
4 PGN MSB xx
5 PGN 2ND xx
6 PGN LSB xx
7 Destination Address xx
8 Source Address xx
9 Priority 0…7
10 Data Field Start xx
:
:
nn CHKSUM xx

TXDATAP, TXDATAPL – Transmit Data Periodically

These two messages are designed and handle data transmission similar to the regular
TXDATA message. They are, however, extended by a message frequency (in
milliseconds). When the gateway receives the TXDATAPL message, the data will be
reflected back to the host system (which is a mandatory feature for gateway
applications).

Note:
• The message frequency (in units of milliseconds) is submitted using two bytes,
thus allowing a maximum time of 65.536 seconds.
• The minimum message frequency is limited to 10 milliseconds.
• A message frequency = 0 will disable (delete) the message.
• The gateway allows up to 50 periodic messages. The DUO version supports 25
periodic messages per port.

Important!
In accordance with the SAE j1939 protocol, the periodic transmission of PGNs
applies only to regular 8-byte data frames, i.e. any messages requiring the

9
 Transport protocol (up to 1785 bytes) will be ignored and the message will not
be acknowledged.

Message Identifier: 17/18

Total Length: Variable (21 with 8 data bytes)
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB xx
2 Length LSB xx
3 MSG_ID_TXP 17/18
4 PGN MSB xx
5 PGN 2ND xx
6 PGN LSB xx
7 Destination Address xx
8 Source Address xx
9 Priority 0…7
10 Frequency (MSB) xx
11 Frequency (LSB) xx
12 Data Field Start xx
:
:
nn CHKSUM xx

RXDATA – Receive Data

This message is transmitted to the host device as soon as the jCOM.J1939 gateway
receives a J1939 message. The message can be between 0 and 1785 bytes long.

Note:
• The gateway will not forward any data as long as the filters are not set.
• The gateway will also not forward any data during the Address Claim process
(applies only to the Communication operating mode).

Message Identifier: 4
Total Length: Variable (19 with 8 data bytes)
Response: -

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB xx
2 Length LSB xx

10
3 MSG_ID_RX 4
4 PGN MSB xx
5 PGN 2ND xx
6 PGN LSB xx
7 Destination Address xx
8 Source Address xx
9 Priority 0…7
10 Data Field Start xx
:
:
nn CHKSUM xx

RESET – Gateway Reset

This message requests a gateway reset, causing a re-initialization of all SAE J1939
protocol parameters, which includes setting the operating mode to Listen-Only.

The purpose of the RESET command is for synchronizing the gateway with the host
system. The gateway’s settings will not be affected by a host system power-down,
meaning all filter settings plus negotiated address will remain active. To prevent any
synchronization issues, it is therefore recommended to issue the RESET command as
soon as the host system powers down or starts up.

CAN Baud Rate Switching – The RESET command also allows initializing the gateway
with a CAN baud rate of 250 kbps or 500 kbps. To do so, modify the “Reset Key 3” value
as shown in the message format description below.

Note:
• The gateway-reset command does not affect the heartbeat frequency or ACK
message settings.

Message Identifier: 5
Total Length: 8 bytes
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 5
3 MSG_ID_RESET 5
4 Reset Key 1 0xA5
5 Reset Key 2 0x69
6 Reset Key 3 0x5A for 250 kbps

11
 0x5B for 500 kbps
7 CHKSUM xx

HEART - Heartbeat
This message is per default being transmitted with a one second frequency; it is being
used as a so-called “watchdog” function to monitor the serial connection functionality.

The message contains the hardware and software versions in a form of A.BB.CC (for
instance, 1.02.03):

• A - Major Update
• BB - Minor Update
• CC - Bug Fix

Following the hardware and software versions are two error counters that allow an
insight into the quality of the serial connection:

• Checksum Error
• Byte Stuffing Error

Please be aware that the range of these counters is from 0 to 255, where, at a count
greater than 255, the counter will start at zero again. However, action should be taken
as soon as a certain (project-specific) count has been reached.

The heartbeat message frequency can be adjusted through the SETHEART message,
which also allows suppressing the heartbeat.

Message Identifier: 6
Total Length: 13 bytes
Response: -

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 10
3 MSG_ID_HEART 6
4 HW_VERSIONMAJOR xx
5 HW_VERSIONMINOR xx
6 HW_VERSIONBUGFIX xx
7 SW_VERSIONMAJOR xx
8 SW_VERSIONMINOR xx
9 SW_VERSIONBUGFIX xx

12
10 ERRCNT_CHECKSUM xx
11 ERRCNT_STUFFING xx
12 CHKSUM xx

SETPARAM, SETPARAM1 – Set Protocol Parameters

This message sets the NAME of the control application (CA) according to SAE J1939/81
(Address Claim Process), sets a preferred source address and address range for the
address claim process and starts the Address Claim process.

With using the SETPARAM1 command, as soon as the address claim process is finished
(successful or not), the gateway will send a REPSTATUS message, reporting the address
claim status and the negotiated address.

The parameters in this message are:

• NAME according to SAE Standard

• Source Address (Preferred Address)
• Address Range Bottom (optional; if not used set as NULL address = 254)
• Address Range Top (optional; if not used set as NULL address = 254)
• Operating Mode
o 0 – Listen-Only
o 1 - Communication

Note:
• The Address Claim process is initiated by overwriting the Listen-Only mode
(gateway default) to Communication mode.

Setting the address range or not will impact the Address Claim process:

1. Full SAE J1939/81 compliant address claim with source address and alternative
address range:

The user can set a preferred source address, but, in case the address is already used in
the vehicle network, an alternative address range is available for the address claim
process.

2. Full SAE J1939/81 compliant address claim with only one source address:

Setting both address range parameters to 254 but submitting a source address (i.e.
setting the control application as non-arbitrary-address-capable) will reset the Arbitrary
Address Capable flag in the NAME.

Note:

13
 • SETPARAM, SETPARAM1 will be rejected (i.e. no ACK will be sent) in case the
operating mode is set other than the defined values.
• The SETPARAM1 command (ID = 14) function is identical to the original
SETPARAM command, but in addition it initiates the REPSTATUS message, which
is being transmitted as soon as the Address Claim process is finished. This allows
the host’s program to wait for the REPSTATUS message to obtain the negotiated
source address.

Message Identifier: 7/14

Total Length: 17 bytes
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 14
3 MSG_ID_SET 7/14
4 NAME LSB xx
5 NAME xx
6 NAME xx
7 NAME xx
8 NAME xx
9 NAME xx
10 NAME xx
11 NAME MSB xx
12 Source Address (SA) xx
13 SA Range Bottom xx
14 SA Range Top xx
15 Operating Mode xx
16 CHKSUM xx

REQINFO – Request Information from J1939 Gateway

This message, sent from the host system to the jCOM.J1939gateway, requests the
transmission of the report message REPSTATUS or the version message VERSION
according to the Request ID.

Request ID: REPSTATUS (ID = 9)

VERSION (ID = 13)

Note:
• The gateway will return no message when the Request ID is not the REPSTATUS-
ID.

14
 • Further request IDs may be added in future firmware versions.

Message Identifier: 8
Total Length: 6 bytes
Response: Depending on Request ID

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 3
3 MSG_ID_RQ 8
4 REQUEST_ID xx
5 CHKSUM xx

REPSTATUS - Report J1939 Protocol Status and Source Address

This message reports the address claim status and the negotiated source address.
REPSTATUS is usually a response to the REQINFO message, but is also transmitted when
the source (node) address changed due to an address challenge during operation.

The reported STATUS will be:

01 – Address Claim in Progress

02 – Address Claim Successful – Normal Data Traffic
03 – Address Claim Failed
04 – Listen-Only Mode

The reported SA will be NULLADDRESS (254) when the address claim process is in
progress, the address claim failed, or the operating mode is Listen-Only. In case the
source address is 254, check the J1939 Protocol Status.

Message Identifier: 9
Total Length: 7 bytes
Response: -

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 4
3 MSG_ID_RS 9
4 Status xx
5 Source Address xx
6 CHKSUM xx

15
FLASH – Starts the In-Circuit Programmer
This message starts the internal in-circuit programmer. This is usually invoked by pulling
a pin low during power-up, but with this function it can be started by the host system at
any time. A flash programming tool (Flash Magic) can be used after calling this function.

After sending the FLASH command, all LEDs on the jCOM.J1939will be on. In order to
switch back to normal operation, you need to go through a power-off-on cycle.

Message Identifier: 10
Total Length: 5 bytes
Response: -

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 2
3 MSG_ID_FLASH 10
4 CHKSUM xx

SETACK – Set Acknowledgment

This message allows the activation/deactivation of the acknowledgment message ACK.

Note:
• The ACK message will be active per default, unless overwritten by the host
system.

Message Identifier: 11
Total Length: 6 bytes
Response: ACK (only when activated)

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 3
3 MSG_ID_SETACK 11
4 ACTIVE xx (0-inactive, 1-active)
5 CHKSUM xx

16
SETHEART – Set Heartbeat Frequency
This message allows the setting of the heartbeat frequency in units of milliseconds. The
message frequency is assigned by two bytes, allowing a range of 100 – 5000
milliseconds, i.e. a time of less than 100 milliseconds will be corrected to 100, and a
time of more than 5000 will be corrected to 5000.

Note:
• Passing a heartbeat frequency of 0 will suppress the message, and it will not be
reset to the minimum time of 100 milliseconds.

Message Identifier: 12
Total Length: 7 bytes
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 4
3 MSG_ID_SETHEART 12
4 FREQ MSB xx
5 FREQ LSB xx
6 CHKSUM xx

VERSION – Report Hardware & Software Version

This message is a response to the REQINFO message in which the VERSION ID was used.
The actual data is identical to the HEARTBEAT message. For that reason, requesting the
VERSION message should only be used after the HEARTBEAT message was suppressed.

Message Identifier: 13
Total Length: 11 bytes
Response: -

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 08
3 MSG_ID_VERSION 13
4 HW_VERSIONMAJOR xx
5 HW_VERSIONMINOR xx
6 HW_VERSIONBUGFIX xx
7 SW_VERSIONMAJOR xx

17
8 SW_VERSIONMINOR xx
9 SW_VERSIONBUGFIX xx
10 CHKSUM xx

SETMSGMODE – Set Message Mode

The message mode defines the type of data (PGNs) that is being passed from the
gateway to the host system. This command is only necessary for gateway applications
where the user needs to see all PGNs including those for protocol control.

The settings are:

• 00 – ECU Message Mode (default after RESET) – The gateway reports only PGNs
addressed to the ECU’s source address or the global address.
• 01 – Gateway Message Mode 1 – The gateway reports PGNs addressed to all
destination addresses including the global address (255).
• 02 – Gateway Message Mode 2 – The gateway reports all PGNs as described in
mode 1 but also includes protocol PGNs according to SAE J1939/21 and SAE
J1939/81.

Message Identifier: 15
Total Length: 6 bytes
Response: ACK

Index Code Value

0 MSG_TOKEN_START 192
1 Length MSB 0
2 Length LSB 03
3 MSG_ID_MSGMODE 15
4 MSGMODE xx
5 CHKSUM xx

18