Address Claiming

Overview

Before a J1939 application can start sending and receiving J1939 messages on a network, it must first claim an address. This is done using j1939_claim_address. The Kvaser J1939 library handles the address claim process and protects the address by responding to Address Claimed (AC) messages and Request for Address Claimed from other nodes.

The Kvaser J1939 library does not require claiming an address before sending or receiving single frame messages. All messages will be received by default, including multi-frame broadcast messages (BAM). However, in order to send multi-frame messages and to receive directed multi-frame messages (RTS/CTS), an address must be claimed.

Note

When an address is claimed the application can send RTS/CTS messages from any source address but it will only receive RTS/CTS messages directed to the claimed address.

Claiming an address

Before claiming an address, the application may register an address claim callback function using j1939_register_callbacks. The AC callback function will be called by the library to notify the application of the outcome of the address claim process, see J1939AcCallback. It will also be called if the claim is lost due to another node on the network claiming the same address with a higher priority.

If the address claim is successful, the address claim callback function will be called with the valid argument set to true. This is done after 250 ms if no other node has challenged the claim. If the claim fails because another node has a higher priority, the callback will be called with the valid argument set to false.

If callbacks are not used, the application must regularly call the j1939_read function to process incoming Address Claimed messages. If the claim was unsuccessful or was lost, the j1939_read function will return the error code J1939_STATUS_ADDRESS_CLAIM_LOST on the next read attempt. Otherwise the application can assume that the address claim is successful after 250 ms.

If the address is not needed anymore, the claim can be released using j1939_remove_address_claim.

Note

The address is automatically released when the channel is closed and must be reclaimed if the channel is reopened.

Example. Claim an address.

void my_ac_callback(uint32_t channel, void* context, uint8_t address, bool valid) {
    if (valid) {
        // Address claim successful
    } else {
        // Address claim failed or was lost
    }
}

// Register address claim callback
int status = j1939_register_callbacks(channel_handle, NULL, NULL, NULL, my_ac_callback);
if (status != J1939_STATUS_OK) {
    // Handle error
}
 
// Node name and the address to claim
uint64_t name = 0x123456789ABCDEF0;
uint8_t address = 0x80;
 
// Claim the address
status = j1939_claim_address(channel_handle, address, name);
if (status != J1939_STATUS_OK) {
    // Handle error
}

Using a shared address table

The Kvaser J1939 library can be configured to share the address claims table between multiple applications running on the same computer. This allows multiple applications to use the same source address on the same CAN bus without conflicts. When using a shared address table and two applications claim the same address, other nodes on the bus will only see the highest priority claim but both applications will be able to use the address for sending and receiving both single-frame and multi-frame messages.

Example. Configure the library to use a shared address table.

// Enable shared address table
int status = j1939_configure_shared_address_table(16);

Considerations when using a shared address table

When using a shared address table, all applications become dependent on each other and if one application misbehaves it can affect the other applications. Since the highest priority claim will manage the address claim and TP flow control, it is important that the application does not block the callback thread, or that it regularly calls j1939_read. If an application freezes or crashes without releasing its claimed address, other applications may be affected.

Only one TP session can be active for a given source/destination address pair at a time. Therefore, when using a shared address table, only one application can send multi-frame messages of each type (BAM or RTS/CTS) from a source address at a time and the transmission queue for multi-frame messages is disabled. If an application attempts to send a multi-frame message while another session is active for the same source address, the send will fail with the error code J1939_STATUS_TX_BUFFER_FULL.