Package ixxat :: Package j1939api :: Module J1939api :: Class J1939
[hide private]
[frames] | no frames]

Class J1939

source code

object --+
         |
        J1939

Python Wrapper for the J1939 API. Provides a native python interface to the IXXAT J1939 protocol stack.

Instance Methods [hide private]
 
__init__(self, deviceAddress, lDeviceName, boardIndex, canLine, sXmlFile)
Initializes an instance of J1939 API class.
source code
 
getStackStatus(self)
Gets the status value of the J1939 Stack.
source code
 
send(self, timeout, msg)
Encodes and sends a J1939 message by copying the message into the stack internal transmission queue.
source code
 
receive(self, timeout)
Decodes and returns a J1939 message or error message from the internal receive queue.
source code
 
getRxQueueStatus(self)
Gets the current reception queue status, by representing the current number of messages in the receive queue.
source code
 
registerDataPgn(self, pgn)
Registers a data PGN for reception with the stack.
source code
 
registerReqPgn(self, pgn)
Registers a request PGN for reception with the stack.
source code
 
registerCycPgn(self, pgn, timeout)
Registers a data Rx PGN for timeout supervision.
source code
 
clearPgnList(self)
Removes all registered PGNs from the data, request and cyclic registration list.
source code
 
readSpnList(self, msg)
Retrieves a list of SPNs within a given PGN.
source code
 
readSpnAttr(self, spn)
Retrieves the attributes corresponding to a specific SPN.
source code
 
flushRxQueue(self)
Flushes the reception queue by calling receive until empty
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, deviceAddress, lDeviceName, boardIndex, canLine, sXmlFile)
(Constructor)

source code 

Initializes an instance of J1939 API class. The initialization includes the importation of the XML module file specified by the sXmlFile parameter for the mapping and demapping of the J1939 messages. The initialization also includes the initialization of the J1939 Stack software, which initializes and starts the CAN interface, starts J1939 address claiming and drives the reception and transmission of messages. The start-up of the CAN interface will require some time. The active state of the instance can be checked using the function getStackStatus().

Parameters:
  • deviceAddress - J1939 device address (e.g. 249 for the Off Board Diagnostic-Service Tool #1)
  • lDeviceName - J1939 device name as list of 9 values: Arbitrary Address Capable, Industry Group, Vehicle System Instance, Vehicle System, Function, Function Instance, ECU Instance, Manufacturer Code, Identity Number) (e. g. [0, 0, 0, 0, 129, 0, 0, 400, 123456]
  • boardIndex - Index corresponding to the selected VCIV3 hardware (see GetBoardList()
  • canLine - Can line of the selected hardware
  • sXmlFile - file path for the XML file containing J1939 configuration data
Overrides: object.__init__

getStackStatus(self)

source code 

Gets the status value of the J1939 Stack. Before the status is active, transmissions over the stack will fail.

Returns:
Current stack status TRUE = active (address claiming finished) FALSE = inactive (address claiming not finished)

send(self, timeout, msg)

source code 

Encodes and sends a J1939 message by copying the message into the stack internal transmission queue. Raw encoding can be performed by setting the message type byte of msg. If the raw message type is set, the input parameters will be evaluated as bytes and written directly to the J1939 message data field, otherwise, they will be evaluated as parameters to be converted into their appropriate raw data representation by the API using the information stored in the XML configuration file. Mapped messages return an error on the attempted transmission with an incorrect number of parameters. In the case of a full transmission queue, the Send() function will reattempt transmission until the timeout period has elapsed.

Parameters:
  • timeout - Receive timeout in milliseconds (-1 for infinite)
  • msg - J1939 message in the form of the J1939Message class
Returns:
zero if sending was successful, 1 if a timeout occurred and False if the parameter msg was invalid.

receive(self, timeout)

source code 

Decodes and returns a J1939 message or error message from the internal receive queue. The message type is stored in the least significant bits of the message status byte. Data PGNs will be decoded. Decoding is performed by the Codec unit using the information contained in the XML module file. If the received PGN is not included in the XML configuration file, the message will be decoded as raw, which copies the data from the data field byte for byte to the byte value list, and the raw message type in the message type byte will be set. The Receive() function will wait on an empty queue until the timeout period has elapsed.

Parameters:
  • timeout - Receive timeout in milliseconds (-1 for infinite)
Returns:
J1939 message in the form of the J1939Message class or None if a timeout occurred (nothing received).

getRxQueueStatus(self)

source code 

Gets the current reception queue status, by representing the current number of messages in the receive queue. The queue has a depth of 1024 messages.

Returns:
Current number of messages waiting in the receive queue

registerDataPgn(self, pgn)

source code 

Registers a data PGN for reception with the stack. PGNs not found in XML configuration file will be decoded on reception as raw. The reception of an unregistered message directed to the API (not global) will cause an error message to be sent back to originating node. The reception of a registered data message will cause the message to be entered into the reception queue for retrieval by the user application.

Parameters:
  • pgn - PGN to be registered

registerReqPgn(self, pgn)

source code 

Registers a request PGN for reception with the stack. The reception of an unregistered request message directed to the API (not global) will cause an error message to be sent back to originating node. The reception of a registered request message will cause the message to be entered into the reception queue as a request message for retrieval and handling by the user application.

Parameters:
  • pgn - PGN to be registered of the message to be requested

registerCycPgn(self, pgn, timeout)

source code 

Registers a data Rx PGN for timeout supervision. The function uses the RegisterDataPgn() functionality to register the PGN for reception by the stack and in addition, registers it with a cyclical test array within the API. On the timeout of an actively registered cyclic message, the J1939API_USR_ERR_CYC_TIMEOUT error message is entered into the reception queue. Cyclical PGNs are deactivated for testing on timeout, to prevent jamming of the reception queue with timeout messages. Cyclical PGNs are activated by the reception of a corresponding message following the initial registration or a previous cycle timeout.

Remarks: The minimum resolution of the cycle time is 5 milliseconds. Cycle times will be rounded up to the next multiple of the timer resolution. The registration of cyclical PGNs also performs the registration of data PGNs.

Parameters:
  • pgn - PGN to be registered
  • timeout - Required reception cycle time in milliseconds. See Remarks for more information regarding the cycle time.

readSpnList(self, msg)

source code 

Retrieves a list of SPNs within a given PGN. Note: The number of possible SPN structures returned is limited to 256.

Parameters:
  • pgn - PGN from which to retrieve the SPN list
Returns:
SPN list

readSpnAttr(self, spn)

source code 

Retrieves the attributes corresponding to a specific SPN. The applicable value can be determined by taking the returned value from the J1939 message, multiplying it by its resolution and adding the offset. The type of variable represented by the attribute entries "res", "off", "min" and "max" depend on the parameter type.

Parameters:
  • spn - SPN from which to retrieve the attributes
Returns:
SPN parameter attribute dictionary with the following keys:
  • "name" : string representing name of the suspect parameter
  • "res" : resolution of the value
  • "off" : offset of the value
  • "min" : minimum allowable value
  • "max" : maximum allowable value
  • "type" : type of value (possible are 'unknown', 'integer', 'float', 'ASCII', 'BitField', 'binary' and 'BLOB')
  • "unit" : string representing the units of the value