API Documentation

CAN

Usage #include <PolySyncCAN.hpp>

The CAN API helps users to interface with devices using Controller Area Network protocols commonly found in automotive and industrial applications.

The CAN API contains an abstraction for the CAN Module called CANChannel that provides this functionality.

Depending on the system configuration, the CAN API can be using Kvaser Linuxcan or SocketCAN libraries. PolySync references target of the symbolic link for polysync/lib/libpolysync_can.so. The two targets are libpolysync_can_socketcan.so and libpolysync_can_linuxcan.so.

CANChannel

The CANChannel class provides basic functions for reading and writing data to and from CAN based devices from sensors to actuators.

Static Public Attributes

static constexpr ps_timestamp t_100ms = 100000 ( )

The constant value of 100000 microseconds, which is equal to 100 milliseconds.

This is used as a default timing allowance in drainSendBuffer() and read()

Public Member Functions

CANChannel::CANChannel ( … )

The CANChannel Constructor will open a CAN channel based on the System ID parameter.

Parameters
in/out type name description
in const ulong systemId This is the system identifier for the channel. See ps_can_channel.system_id for details.
in const ulong flags This flags configuration flags for the channel. It can be a combination of the PSYNC_CANOPEN* flags.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_OSERR - If there is a problem loading the CAN libraries
    • DTC_CONFIG - If there is a problem loading the symbol information

CANChannel::~CANChannel ( )

The CANChannel destructor will close the channel prior to deallocation.

CANChannel::setBitRate ( … )

This will configure the CAN channel to a specific bit rate.

The possible bit rates are defined in the ps_datarate_kind value that is the bitRate parameter.

Parameters
in/out type name description
in ps_datarate_kind bitRate The rate that data is transmitted [bits per second]. See ps_datarate_kind for enumerated values.
Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_OSERR - If there is a problem loading the CAN libraries
    • DTC_CONFIG - If there is a problem loading the symbol information

CANChannel::getHardwareId ( )

This will return the serial number of the adapter hardware, not the channel hardware.

Returns
  • ulong - Hardware ID
Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the system ID or device ID is invalid

CANChannel::getCircuitId ( )

This will return the index of the channel/circuit for a given piece of hardware.

Returns
  • ulong - Circuit ID
Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the system ID or device ID is invalid

CANChannel::getSystemId ( )

This will return the CAN channel index on this Host machine.

Returns
  • ulong - System ID
Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the system ID or device ID is invalid

CANChannel::goOnBus ( )

This will enable an interaction with the CAN bus.

Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the system ID or device ID is invalid

CANChannel::goOffBus ( )

This will disable an interaction with the CAN bus.

Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the system ID or device ID is invalid

CANChannel::drainSendBuffer ( … )

This will wait until all CAN messages for the specified handle are sent, or the timeout period expires.

Parameters
in/out type name description
in const ps_timestamp timeout = t_100ms The maximum time allowed for drain. A value of zero means wait forever. [microseconds]
Exceptions
  • Throws polysync::DTCExceptionon failure:

CANChannel::getInputFrameFlags ( )

This will get the flags set from the updated data following call to CANChannel::read(). PSYNC_CAN_MSG_STD represents a standard frame.

Returns
  • ulong - Flags

CANChannel::getInputFrameHardwareTimestamp ( )

getInputFrameHardwareTimestamp will get the hardware-provided timestamp, which is relative to a device power-up from the CAN data.

The returned value is in microseconds.

Returns
  • ps_timestamp - The hardware timestamp value from the input CAN frame

CANChannel::getInputFrameId ( )

This will get the frame ID for a given input frame from the CAN bus.

Returns
  • ulong - Frame ID

CANChannel::getOutputFrameId ( )

This will get the values set to the outputFrame by CANChannel::write().

CANChannel::getInputFramePayloadSize ( )

getInputFramePayloadSize will get the number of bytes in the payload data from the latest CAN CANChannel::read() operation.

Returns
  • ulong - Size of the data read from the CAN bus

CANChannel::getInputFramePolySyncTimestamp ( )

This will get the PolySync timestamp from the latest CAN read() operation.

The return value is in microseconds.

Returns

std::array< uchar, 8 > CANChannel::read ( … )

This will read the data from the CAN bus using the selected channel.

Parameters
in/out type name description
in ps_timestamp waitTime = t_100ms The maximum duration that PolySync will attempt to read data from a channel. Default is 100. [milliseconds]
Returns
  • Array containing CAN frame data

polysync::CAN::Channel ch0{ systemId0, PSYNC_CAN_OPEN_EXTENDED };
// Get the CAN frame
auto canBuffer = ch0.read();
// Check the values of various members for more data about the input frame.
auto id = ch0.getInputFrameId();
...

Exceptions
  • Throws polysync::DTCExceptionon failure

CANChannel::setOutputFrameFlags ( … )

This will set the output frame flags for a standard CAN frame prior to calling CANChannel::write().

Parameters
in/out type name description
in ulong flags This represents a flag value for a standard CAN frame, e.g. PSYNC_CAN_MSG_STD.

CANChannel::setOutputFrameHardwareTimestamp ( … )

This will set a hardware timestamp in preparation for a CANChannel::write() operation.

Parameters
in/out type name description
in ps_timestamp hwTimestamp The hardware-provided timestamp, relative to device power-up. [microseconds]

CANChannel::setOutputFrameId ( … )

This will set the output CAN frame ID in preparation for a CANChannel::write() operation.

Parameters
in/out type name description
in ulong id The CAN frame identifier.

CANChannel::setOutputFramePayloadSize ( … )

This will set the output frame payload size in preparation for a CANChannel::write() operation.

Parameters
in/out type name description
in ulong frameSize The number of bytes in the payload.

CANChannel::write ( … )

This will write a CAN frame to the CAN channel at the system ID set in the constructor.

Parameters
in/out type name description
in std::array< uchar , 8 > dataForOutput CAN frame containing data to send.

  polysync::CAN::Channel ch0{ systemId0, PSYNC_CAN_OPEN_EXCLUSIVE };
  ch0.setOutputFrameId( SENSOR_CONFIG_ID );
  ch0.setOutputFramePayloadSize( SENSOR_FRAME_SIZE );
  ch0.setOutpuFrameFlags( PSYNC_CAN_MSG_STD );
  std::array< uchar, 8 > outputFrame{ your CAN buffer here {0} };
  channel.write( outputFrame );

Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the write operation failed
    • DTC_INTR - If the write operation was interrupted

API Functions

The CAN API Functions that are not associated with a class.

CANChannel::getChannelCount ( )

This will get the number of CAN channels available on the host machine.

Returns
  • 0 if no channels exist
Exceptions
  • Throws polysync::DTCExceptionon failure:
    • DTC_USAGE - If there is an invalid argument
    • DTC_CONFIG - If the device ID is invalid, there is no resource detected