HSK Controller Area Network headers. More...

This graph shows which files directly or indirectly include this file:

Macros
#define	CAN_ERROR 0xff
	Value returned by functions in case of an error. More...

#define	CAN0 0
	CAN node 0. More...

#define	CAN1 1
	CAN node 1. More...

#define	CAN0_IO_P10_P11 0
	CAN node 0 IO RX on P1.0, TX on P1.1. More...

#define	CAN0_IO_P16_P17 1
	CAN node 0 IO RX on P1.6, TX on P1.7. More...

#define	CAN0_IO_P34_P35 2
	CAN node 0 IO RX on P3.4, TX on P3.5. More...

#define	CAN0_IO_P40_P41 3
	CAN node 0 IO RX on P4.0, TX on P4.1. More...

#define	CAN1_IO_P01_P02 4
	CAN node 1 IO RX on P0.1, TX on P0.2. More...

#define	CAN1_IO_P14_P13 5
	CAN node 1 IO RX on P1.4, TX on P1.3. More...

#define	CAN1_IO_P32_P33 6
	CAN node 1 IO RX on P3.2, TX on P3.3. More...

#define	CAN_ENDIAN_INTEL 0
	Little endian signal encoding. More...

#define	CAN_ENDIAN_MOTOROLA 1
	Big endian signal encoding. More...

#define	CAN_STATUS_LEC 0
	The Last Error Code field provides the error triggered by the last message on the bus. More...

#define	CAN_STATUS_TXOK 1
	Message Transmitted Successfully. More...

#define	CAN_STATUS_RXOK 2
	Message Received Successfully. More...

#define	CAN_STATUS_ALERT 3
	Alert Warning. More...

#define	CAN_STATUS_EWRN 4
	Error Warning Status. More...

#define	CAN_STATUS_BOFF 5
	Bus-off Status. More...

Typedefs
typedef ubyte	hsk_can_node
	CAN node identifiers. More...

typedef ubyte	hsk_can_msg
	CAN message object identifiers. More...

typedef ubyte	hsk_can_fifo
	CAN message FIFO identifiers. More...

Functions
void	hsk_can_init (const ubyte pins, const ulong baud)
	Setup CAN communication with the desired baud rate. More...

void	hsk_can_enable (const hsk_can_node node)
	Go live on the CAN bus. More...

void	hsk_can_disable (const hsk_can_node node)
	Disable a CAN node. More...

ubyte	hsk_can_status (const hsk_can_node node, const ubyte field)
	Returns a status field of a CAN node. More...

hsk_can_msg	hsk_can_msg_create (const ulong id, const bool extended, const ubyte dlc)
	Creates a new CAN message. More...

ubyte	hsk_can_msg_connect (const hsk_can_msg msg, const hsk_can_node node)
	Connect a message object to a CAN node. More...

ubyte	hsk_can_msg_disconnect (const hsk_can_msg msg)
	Disconnect a CAN message object from its CAN node. More...

ubyte	hsk_can_msg_delete (const hsk_can_msg msg)
	Delete a CAN message object. More...

void	hsk_can_msg_getData (const hsk_can_msg msg, ubyte *const msgdata)
	Gets the current data in the CAN message. More...

void	hsk_can_msg_setData (const hsk_can_msg msg, const ubyte *const msgdata)
	Sets the current data in the CAN message. More...

void	hsk_can_msg_send (const hsk_can_msg msg)
	Request transmission of a message. More...

bool	hsk_can_msg_sent (const hsk_can_msg msg)
	Return whether the message was successfully sent between this and the previous call of this method. More...

void	hsk_can_msg_receive (const hsk_can_msg msg)
	Return the message into RX mode after sending a message. More...

bool	hsk_can_msg_updated (const hsk_can_msg msg)
	Return whether the message was updated via CAN bus between this call and the previous call of this method. More...

hsk_can_fifo	hsk_can_fifo_create (ubyte size)
	Creates a message FIFO. More...

void	hsk_can_fifo_setupRx (hsk_can_fifo fifo, const ulong id, const bool extended, const ubyte dlc)
	Set the FIFO up for receiving messages. More...

void	hsk_can_fifo_setRxMask (const hsk_can_fifo fifo, ulong msk)
	Changes the ID matching mask of an RX FIFO. More...

ubyte	hsk_can_fifo_connect (const hsk_can_fifo fifo, const hsk_can_node node)
	Connect a FIFO to a CAN node. More...

ubyte	hsk_can_fifo_disconnect (const hsk_can_fifo fifo)
	Disconnect a FIFO from its CAN node. More...

ubyte	hsk_can_fifo_delete (const hsk_can_fifo fifo)
	Delete a FIFO. More...

void	hsk_can_fifo_next (const hsk_can_fifo fifo)
	Select the next FIFO entry. More...

ulong	hsk_can_fifo_getId (const hsk_can_fifo fifo)
	Returns the CAN ID of the selected FIFO entry. More...

bool	hsk_can_fifo_updated (const hsk_can_fifo fifo)
	Return whether the currently selected FIFO entry was updated via CAN bus between this call and the previous call of this method. More...

void	hsk_can_fifo_getData (const hsk_can_fifo fifo, ubyte *const msgdata)
	Gets the data from the currently selected FIFO entry. More...

void	hsk_can_data_setSignal (ubyte *const msg, const bool motorola, const bool sign, const ubyte bitPos, const char bitCount, const ulong value)
	Sets a signal value in a data field. More...

ulong	hsk_can_data_getSignal (const ubyte *const msg, const bool motorola, const bool sign, const ubyte bitPos, const char bitCount)
	Get a signal value from a data field. More...

Detailed Description

HSK Controller Area Network headers.

This file contains the function prototypes to initialize and engage in CAN communication over the builtin CAN nodes 0 and 1.

Author: kami

CAN Message/Signal Tuples

The recommended way to use messages and signals is not to specify them inline, but to provide defines with a set of parameters.

These tupples should follow the following pattern:

#define MSG_<MSGNAME> <id>, <extended>, <dlc>

#define SIG_<SIGNAME> <motorola>, <signed>, <bitPos>, <bitCount>

The symbols have the following meaning:

MSGNAME: The name of the message in capitals, e.g. AFB_CHANNELS
id: The CAN id of the message, e.g. 0x403
extended: Whether the CAN ID is extended or not, e.g. 0 for a regular ID
dlc: The data length count of the message, e.g. 3
SIGNAME: The name of the signal in capitals, e.g. AFB_CHANNEL0_CURRENT
motorola: Whether the signal is in big endian (Motorola) format
signed: Whether the signal is signed
bitPos: The starting bit of the signal, e.g. 0
bitCount: The length of the signal in bits, e.g. 10

Tuples using the specified format can directly be used as parameters for several functions in the library.

CAN Node Management

There are 7 port pairs available for CAN communication, check the CANn_IO_* defines. Four for the node CAN0 and three for CAN1.

Message Object Management

The MultiCAN module offers up to 32 message objects. New messages are set up for receiving messages. Message object can be switched from RX to TX mode and back with the hsk_can_msg_send() and hsk_can_msg_receive() functions.

FIFOs

FIFOs are the weapon of choice when dealing with large numbers of individual messages or when receving multiplexed data. In most use cases only the latest version of a message is relevant and FIFOs are not required. But messages containing multiplexed signals may contain critical signals that would be overwritten by a message with the same ID, but a different multiplexor.

If more message IDs than available message objects are used to send and/or receive data, there is no choice but to use a FIFO.

Currently only RX FIFOs are supported.

A FIFO can act as a buffer the CAN module can store message data in until it can be dealt with. The following example illustrates how to read from a FIFO:

if (hsk_can_fifo_updated(fifo0)) {
        hsk_can_fifo_getData(fifo0, data0);
        hsk_can_fifo_next(fifo0);
        select = hsk_can_data_getSignal(data0, SIG_MULTIPLEXOR);
        [...]
}

When using a mask to accept several messages checking the ID becomes necessary:

if (hsk_can_fifo_updated(fifo0)) {
        switch (hsk_can_fifo_getId()) {
        case MSG_0_ID:
                hsk_can_fifo_getData(fifo0, data0);
                [...]
                break;
        case MSG_1_ID:
                hsk_can_fifo_getData(fifo0, data1);
                [...]
                break;
        [...]
        }
        hsk_can_fifo_next(fifo0);
}

FIFOs draw from the same message object pool regular message objects do.

Message Data

The hsk_can_data_setSignal() and hsk_can_data_getSignal() functions allow writing and reading signals across byte boundaries to and from a buffer.

For big endian signals the bit position of the most significant bit must be supplied (highest bit in the first byte). For little endian signals the least significant bit must be supplied (lowest bit in the first byte).

This conforms to the way signal positions are stored in Vector CANdb++ DBC files.

Macro Definition Documentation

§ CAN0

#define CAN0 0

CAN node 0.

§ CAN0_IO_P10_P11

#define CAN0_IO_P10_P11 0

CAN node 0 IO RX on P1.0, TX on P1.1.

§ CAN0_IO_P16_P17

#define CAN0_IO_P16_P17 1

CAN node 0 IO RX on P1.6, TX on P1.7.

§ CAN0_IO_P34_P35

#define CAN0_IO_P34_P35 2

CAN node 0 IO RX on P3.4, TX on P3.5.

§ CAN0_IO_P40_P41

#define CAN0_IO_P40_P41 3

CAN node 0 IO RX on P4.0, TX on P4.1.

§ CAN1

#define CAN1 1

CAN node 1.

§ CAN1_IO_P01_P02

#define CAN1_IO_P01_P02 4

CAN node 1 IO RX on P0.1, TX on P0.2.

§ CAN1_IO_P14_P13

#define CAN1_IO_P14_P13 5

CAN node 1 IO RX on P1.4, TX on P1.3.

§ CAN1_IO_P32_P33

#define CAN1_IO_P32_P33 6

CAN node 1 IO RX on P3.2, TX on P3.3.

§ CAN_ENDIAN_INTEL

#define CAN_ENDIAN_INTEL 0

Little endian signal encoding.

Deprecated:: In favour of shorter and cleaner code the hsk_can_data_getSignal() and hsk_can_data_setSignal() functions were switched to using boolean (motorola positive) logic

§ CAN_ENDIAN_MOTOROLA

#define CAN_ENDIAN_MOTOROLA 1

Big endian signal encoding.

Deprecated:: In favour of shorter and cleaner code the hsk_can_data_getSignal() and hsk_can_data_setSignal() functions were switched to using boolean (motorola positive) logic

§ CAN_ERROR

#define CAN_ERROR 0xff

Value returned by functions in case of an error.

Typedef Documentation

§ hsk_can_fifo

typedef ubyte hsk_can_fifo

CAN message FIFO identifiers.

§ hsk_can_msg

typedef ubyte hsk_can_msg

CAN message object identifiers.

§ hsk_can_node

typedef ubyte hsk_can_node

CAN node identifiers.

Function Documentation

§ hsk_can_data_getSignal()

ulong hsk_can_data_getSignal	(	const ubyte *const	msg,
		const bool	motorola,
		const bool	sign,
		const ubyte	bitPos,
		const char	bitCount
	)

Get a signal value from a data field.

Parameters

msg	The message data field to read from
motorola	Indicates big endian (Motorola) encoding
sign	Indicates whether the value has a signed type
bitPos	The bit position of the signal
bitCount	The length of the signal

Returns: The signal from the data field msg

Here is the call graph for this function:

§ hsk_can_data_setSignal()

void hsk_can_data_setSignal	(	ubyte *const	msg,
		const bool	motorola,
		const bool	sign,
		const ubyte	bitPos,
		const char	bitCount,
		const ulong	value
	)

Sets a signal value in a data field.

Parameters

msg	The message data field to write into
motorola	Indicates big endian (Motorola) encoding
sign	Indicates whether the value has a signed type
bitPos	The bit position of the signal
bitCount	The length of the signal
value	The signal value to write into the data field

The sign parameter is not required for setting signals, it is just there so that one signal configuration tuple suffices for hsk_can_data_setSignal() and hsk_can_data_getSignal().

Here is the call graph for this function:

§ hsk_can_disable()

void hsk_can_disable ( const hsk_can_node node )

Disable a CAN node.

This completely shuts down a CAN node, cutting it off from the internal clock, to reduce energy consumption.

Parameters

node	The CAN node to disable

§ hsk_can_enable()

void hsk_can_enable ( const hsk_can_node node )

Go live on the CAN bus.

To be called when everything is set up.

Parameters

node	The CAN node to enable

§ hsk_can_fifo_connect()

ubyte hsk_can_fifo_connect	(	const hsk_can_fifo	fifo,
		const hsk_can_node	node
	)

Connect a FIFO to a CAN node.

Parameters

fifo	The identifier of the FIFO
node	The CAN node to connect to

Return values

CAN_ERROR	The given FIFO is not valid
0	Success

Here is the call graph for this function:

§ hsk_can_fifo_create()

hsk_can_fifo hsk_can_fifo_create ( ubyte size )

Creates a message FIFO.

FIFOs can be used to ensure that multiplexed signals are not lost.

For receiving multiplexed signals it is recommended to use a FIFO as large as the number of multiplexed messages that might occur in a single burst.

If the multiplexor is large, e.g. 8 bits, it's obviously not possible to carve a 256 messages FIFO out of 32 message objects. Make an educated guess and hope that the signal provider is not hostile.

If the number of available message objects is at least one, but less than the requested length this function succeeds, but the FIFO is only created as long as possible.

Parameters

size	The desired FIFO size

Return values

CAN_ERROR	Creating the FIFO failed
[0;32[	The created FIFO id

Slave Objects

Slave objects are put into the same list as the base message object, so it can be used as a slave as well.

Always configure slave messages as TXSLAVEs, because in RXMODE the setting is ignored anyway.

Message Pointers

MOFGPRn of the base object holds the message pointers that define the list boundaries. SEL will be used to keep track of where to read/write the next message when interacting with the FIFO.

§ hsk_can_fifo_delete()

ubyte hsk_can_fifo_delete ( const hsk_can_fifo fifo )

Delete a FIFO.

Parameters

fifo	The identifier of the FIFO

Return values

CAN_ERROR	The given FIFO is not valid
0	Success

Here is the call graph for this function:

§ hsk_can_fifo_disconnect()

ubyte hsk_can_fifo_disconnect ( const hsk_can_fifo fifo )

Disconnect a FIFO from its CAN node.

This takes the FIFO out of active communication, without deleting it.

Parameters

fifo	The identifier of the FIFO

Return values

CAN_ERROR	The given FIFO is not valid
0	Success

Here is the call graph for this function:

§ hsk_can_fifo_getData()

void hsk_can_fifo_getData	(	const hsk_can_fifo	fifo,
		ubyte *const	msgdata
	)

Gets the data from the currently selected FIFO entry.

This writes DLC bytes from the FIFO entry into msgdata.

Parameters

fifo	The identifier of the FIFO
msgdata	The character array to store the message data in

Here is the call graph for this function:

§ hsk_can_fifo_getId()

ulong hsk_can_fifo_getId ( const hsk_can_fifo fifo )

Returns the CAN ID of the selected FIFO entry.

Parameters

fifo	The ID of the FIFO

Returns: The ID of the currently selected message object

§ hsk_can_fifo_next()

void hsk_can_fifo_next ( const hsk_can_fifo fifo )

Select the next FIFO entry.

The hsk_can_fifo_updated() and hsk_can_fifo_getData() functions always refer to a certain message within the FIFO. This function selects the next entry.

Parameters

fifo	The ID of the FIFO to select the next entry from

§ hsk_can_fifo_setRxMask()

void hsk_can_fifo_setRxMask	(	const hsk_can_fifo	fifo,
		ulong	msk
	)

Changes the ID matching mask of an RX FIFO.

Every RX FIFO is setup to receive only on complete ID matches. This function allows updating the mask.

To generate a mask from a list of IDs use the following formula:

$msk = \sim(id_0 | id_1 | ... | id_n) | (id_0 \& id_1 \& ... \& id_n)$

Precondition: hsk_can_fifo_setupRx()

Parameters

fifo	The FIFO to change the RX mask for
msk	The bit mask to set for the FIFO

§ hsk_can_fifo_setupRx()

void hsk_can_fifo_setupRx	(	hsk_can_fifo	fifo,
		const ulong	id,
		const bool	extended,
		const ubyte	dlc
	)

Set the FIFO up for receiving messages.

Parameters

fifo	The FIFO to setup
id	The message ID.
extended	Set this to 1 for an extended CAN message
dlc	The data length code, # of bytes in the message, valid values range from 0 to 8

§ hsk_can_fifo_updated()

bool hsk_can_fifo_updated ( const hsk_can_fifo fifo )

Return whether the currently selected FIFO entry was updated via CAN bus between this call and the previous call of this method.

It can be used to decide when to call hsk_can_fifo_getData() and hsk_can_fifo_next().

Parameters

fifo	The identifier of the FIFO to check

Return values

1	The FIFO entry was updated since the last call of this function
0	The FIFO entry has not been updated since the last call of this function

Here is the call graph for this function:

§ hsk_can_init()

void hsk_can_init	(	const ubyte	pins,
		const ulong	baud
	)

Setup CAN communication with the desired baud rate.

The CAN node is chosen with the pin configuration.

The bus still needs to be enabled after being setup.

Parameters

pins	Choose one of 7 CANn_IO_* configurations
baud	The target baud rate to use

Configure the Bit Timing Unit

Note: Careful study of section 16.1.3 "CAN Node Control" of the XC878 Reference Manual is advised before changing the following code.; Minima and maxima are specified in ISO 11898.

One bit is s separated into 3 blocks, each of which are multiples of a time quantum. The size of the time quantum (TQ) is controlled by the BRP and DIV8 bits. Because TSYNC is fixed to a single quantum, the other segments should be made up of a minimum of TQs, so TSYNC doesn't get too short (making a bit up of more TQs requires each one to be shorter at the same baud rate). However, the minimum number of TQs is 8 and some spare quantums are needed to adjust the timing between each bit transmission.

Time Slice	Value	Minimum	Encoding
TSYNC	1	Fixed	Implicite
TSEG1	8	3	7
TSEG2	3	2	2
SWJ	4	-	3

The above values provide 4 time quantums to adjust between bits without dropping below 8 quantums. The adjustment value is provided with the SWJ time slice.

The sample point is between TSEG1 and TSEG2, i.e. at 75%.

This means one bit requires 12 cycles. The BRP bits can be used to achieve the desired baud rate:

$baud = 48000000 / 12 / BRP$

$BRP = 48000000 / 12 / baud$

The encoding of BRT is also VALUE+1.

I/O Configuration

There are 7 different I/O pin configurations, four are availabe to node 0 and three to node 1.

See also: Section 16.1.11 "MultiCAN Port Control" of the XC878 Reference Manual

§ hsk_can_msg_connect()

ubyte hsk_can_msg_connect	(	const hsk_can_msg	msg,
		const hsk_can_node	node
	)

Connect a message object to a CAN node.

Parameters

msg	The identifier of the message object
node	The CAN node to connect to

Return values

CAN_ERROR	The given message is not valid
0	Success

Here is the call graph for this function:

§ hsk_can_msg_create()

hsk_can_msg hsk_can_msg_create	(	const ulong	id,
		const bool	extended,
		const ubyte	dlc
	)

Creates a new CAN message.

Note that only up to 32 messages can exist at any given time.

Extended messages have 29 bit IDs and non-extended 11 bit IDs.

Parameters

id	The message ID.
extended	Set this to 1 for an extended CAN message.
dlc	The data length code, # of bytes in the message, valid values range from 0 to 8.

Return values

CAN_ERROR	Creating the message failed
[0;32[	A message identifier

§ hsk_can_msg_delete()

ubyte hsk_can_msg_delete ( const hsk_can_msg msg )

Delete a CAN message object.

Parameters

msg	The identifier of the message object

Return values

CAN_ERROR	The given message is not valid
0	Success

Here is the call graph for this function:

§ hsk_can_msg_disconnect()

ubyte hsk_can_msg_disconnect ( const hsk_can_msg msg )

Disconnect a CAN message object from its CAN node.

This takes a CAN message out of active communication, without deleting it.

Parameters

msg	The identifier of the message object

Return values

CAN_ERROR	The given message is not valid
0	Success

Here is the call graph for this function:

§ hsk_can_msg_getData()

void hsk_can_msg_getData	(	const hsk_can_msg	msg,
		ubyte *const	msgdata
	)

Gets the current data in the CAN message.

This writes DLC bytes from the CAN message object into msgdata.

Parameters

msg	The identifier of the message object
msgdata	The character array to store the message data in

§ hsk_can_msg_receive()

void hsk_can_msg_receive ( const hsk_can_msg msg )

Return the message into RX mode after sending a message.

After sending a message the messages with the same ID from other bus participants are ignored. This restores the original setting to receive messages.

Parameters

msg	The identifier of the message to receive

§ hsk_can_msg_send()

void hsk_can_msg_send ( const hsk_can_msg msg )

Request transmission of a message.

Parameters

msg	The identifier of the message to send

§ hsk_can_msg_sent()

bool hsk_can_msg_sent ( const hsk_can_msg msg )

Return whether the message was successfully sent between this and the previous call of this method.

Parameters

msg	The identifier of the message to check

Return values

1	The message was sent since the last call of this function
0	The message has not been sent since the last call of this function

§ hsk_can_msg_setData()

void hsk_can_msg_setData	(	const hsk_can_msg	msg,
		const ubyte *const	msgdata
	)

Sets the current data in the CAN message.

This writes DLC bytes from msgdata to the CAN message object.

Parameters

msg	The identifier of the message object
msgdata	The character array to get the message data from

§ hsk_can_msg_updated()

bool hsk_can_msg_updated ( const hsk_can_msg msg )

Return whether the message was updated via CAN bus between this call and the previous call of this method.

An update does not entail a change of message data. It just means the message was received on the CAN bus.

This is useful for cyclic message occurance checks.

Parameters

msg	The identifier of the message to check

Return values

1	The message was updated since the last call of this function
0	The message has not been updated since the last call of this function

§ hsk_can_status()

ubyte hsk_can_status	(	const hsk_can_node	node,
		const ubyte	field
	)

Returns a status field of a CAN node.

Parameters

node	The CAN node to return the status of
field	The status field to select

Returns: The status field state

See also: CAN Node Status Fields

Macros

Typedefs

Functions

Detailed Description

CAN Message/Signal Tuples

CAN Node Management

Message Object Management

FIFOs

Message Data

Macro Definition Documentation

§ CAN0

§ CAN0_IO_P10_P11

§ CAN0_IO_P16_P17

§ CAN0_IO_P34_P35

§ CAN0_IO_P40_P41

§ CAN1

§ CAN1_IO_P01_P02

§ CAN1_IO_P14_P13

§ CAN1_IO_P32_P33

§ CAN_ENDIAN_INTEL

§ CAN_ENDIAN_MOTOROLA

§ CAN_ERROR

Typedef Documentation

§ hsk_can_fifo

§ hsk_can_msg

§ hsk_can_node

Function Documentation

§ hsk_can_data_getSignal()

§ hsk_can_data_setSignal()

§ hsk_can_disable()

§ hsk_can_enable()

§ hsk_can_fifo_connect()

§ hsk_can_fifo_create()

§ hsk_can_fifo_delete()

§ hsk_can_fifo_disconnect()

§ hsk_can_fifo_getData()

§ hsk_can_fifo_getId()

§ hsk_can_fifo_next()

§ hsk_can_fifo_setRxMask()

§ hsk_can_fifo_setupRx()

§ hsk_can_fifo_updated()

§ hsk_can_init()

§ hsk_can_msg_connect()

§ hsk_can_msg_create()

§ hsk_can_msg_delete()

§ hsk_can_msg_disconnect()

§ hsk_can_msg_getData()

§ hsk_can_msg_receive()

§ hsk_can_msg_send()

§ hsk_can_msg_sent()

§ hsk_can_msg_setData()

§ hsk_can_msg_updated()

§ hsk_can_status()