CANbus Device Support for EPICS
Version 2.9
Andrew Johnson <anj@aps.anl.gov>
This document describes the device support provided with the TEWS TIP810 Industry-Pack CANbus driver under EPICS. There are two related documents which describe the lower levels of software which are also required to provide the interface to the CANbus: drvTip810 - CAN Bus Driver and drvIpac - Industry Pack Driver.
Device Support routines have been provided for the following record types:
The device support behaviour for these record types is substantially the same. The differences are discussed individually for each record type in section 3 below.
Also available is the ability to check the status of the Tip810 CANbus interface, using:
The support for this record type is significantly different to the others so is described seperately in section 4.
All communication with the CANbus hardware is performed using the routines defined in the generic header file canBus.h, thus these device support routines can be used with hardware other than the Tews TIP810 Industry-Pack module if a suitable driver is written. It is not currently possible for two such CANbus drivers to co-exist in the same IOC however.
Each record is associated with a single message identifier on a particular CANbus, although any identifier can be used for more than one record simultaneously. This allows several items of input data to be encoded into one message and each record just picks out the relevant part of the message data for its own use. This technique cannot be used for output records however, for obvious reasons.
Records should have their Device Type (DTYP) field set
to CANbus
for which the hardware address field
(INP or OUT) is an Instrument I/O type
(INST_IO), which provides for a single address string.
This contains a number of elements, some of which are optional, and is
formatted as follows:
@busName[/timeout]:identifier[+n..][.offset]parameter
The first element after the @
is the bus name, which should
consist of alphanumeric characters only. The name starts with the first
non-white-space character, and is terminated immediately before the first
/
or :
character in the string.
An oblique stroke after the bus name introduces an optional timeout element, which is an integer number of milli-seconds to wait for a response from the CANbus device. If the timeout element is omitted from the address string, an indefinite delay will be permitted. If the CANbus goes into a Bus Off state and there are output or RTR records without a timeout specified, the scan tasks which process these records will be halted until the bus recovers.
The CANbus message identifier is preceded by a colon, and must result in one of the legal CANbus identifiers in the range 0 through 2047 (with holes). The identifier itself can be specified as a single number, or in several parts separated by plus signs, which are all summed. The numbers here can be given in decimal, hex or octal as desired using the standard 'C' syntax.
If the identifier is followed by a decimal point, the following element is an optional byte offset into the CANbus message where the data may be found. The offset is a number from zero to seven, and defaults to zero if the element is omitted. Note that for output records this offset is not used.
The final parameter element is usually a signed integer introduced by a space or tab character, and is used in different ways by the various different record types (see below).
All input record types support asynchronous processing. This is necessary because there may be a significant delay between sending a Remote Transmission Request (RTR) message out on the CANbus and the addressed device returning a value. With asynchronous processing support this delay will not hold up other EPICS activities which do not depend on the results returned to the input record (i.e. records in a different lock-set). The timeout address field is used to start a timer when the RTR is sent, and if no response is received within the given period the record is put in the TIMEOUT_ALARM status with a severity of INVALID_ALARM.
The CANbus messages handled and generated by the device support routines depend on the setting of the SCAN field of the particular record. When a passive or periodically scanned input record is processed, a CANbus Remote Transmission Request message is sent and record processing is suspended until the relevant reply is received. A passive or periodically scanned output record causes a CANbus message to be generated each time it is processed.
All record types support the I/O Interrupt scan type. Records which use this scan mechanism will be processed whenever a CANbus message is received with the relevant identifier. For an output record, the message received must be a Remote Transmission Request, and an EPICS processing chain can be used to obtain the value to be returned in response to this request.
It is obviously desirable to avoid unnecessary CANbus message traffic, thus if several input data items are encoded in the same CANbus message identifier which are destined for several input records, all of the records except one should be set to I/O Interrupt scanning. When it is processed this record will generate a single CANbus RTR message to ask for the data from the remote node. The reply will be distributed to all of the records waiting on this particular message identifier.
Records will be placed in an alarm state in the event of the CANbus interface signalling a Bus Error or Bus Off event, or if the remote CAN device does not respond to an RTR message within the specified timeout interval. The alarm status and severity meanings are given in the following table:
Status Severity Description COMM_ALARM INVALID_ALARM CAN Bus Error or Bus Off event TIMEOUT_ALARM INVALID_ALARM Device or RTR Timeout UDF_ALARM INVALID_ALARM Internal Error
The major difference between the various record types supported is in the use of the miscellaneous address parameter which defines how the CANbus message data is interpreted.
For Analogue records, the address parameter may be a signed number which
specifies the maximum value of the raw data within the CANbus message, or the
string float
or double
.
The latter formats imply that the CAN message contains an IEEE floating-point
number in the same format as that used by the IOC's CPU - no byte swapping or
other format conversion is provided other than converting a float to the double
value used by the record. Note that no engineering units conversion is
performed when either of these formats is selected.
A numeric parameter specifies a raw integer value with arbitrary width up to 32 bits, but note that the data's LSB must be aligned to the LSB of a message byte. If the parameter given is negative the raw data values are taken to be 2s-complement numbers with the given range and centred about zero, otherwise the value is taken to be unsigned, ranging from zero up to the value given. In both cases if the parameter value is a power of two it will be rounded down by one (64 becomes 63, 0x800 becomes 0x7ff etc). The range is not limited to just powers of two however - e.g. the value 1999 might be used if the data originated from a 3½ digit BCD number (although it must have been converted from BCD to 2s-complement binary before being transmitted in the CAN message).
Analogue records include the ability to perform an automatic engineering
units conversion, depending on the setting of the record's LINR
field. If this is set to NO CONVERSION
the record
value will be identical to the raw value read from the CAN message. When set to
LINEAR
the input range specified by the address
parameter will be mapped directly to the range given by the
EGUL and EGUF fields. This applies even if the
input range is 2s-complement such that the most negative input will give return
the value given by EGUL and the most positive will return
EGUF.
For binary records, the address parameter specifies the bit number within the byte which holds the binary value, where 0 refers to the least significant bit and 7 the most significant. The address offset parameter must be used to select which byte in the message is to be examined, although this byte offset is ignored by the binary output record support.
For the various multi-bit binary records, the address parameter specifies the bit number (0 to 7) of the least significant bit in the bit-field (the number of bits is specified in the record's NOBT field). The address offset parameter is used to select which byte in the message is used, although this is ignored by the output record types. It is not possible for the bit-field to cross a byte boundary, thus the record behaviour is undefined when the sum of the address parameter and NOBT exceeds 8.
The Tip810 module driver software also provides the ability to monitor the status of the CANbus interface chip using Binary Input records. The main use of this device support will be for the Bus Status, Error Status and Data Overrun bits, although any of the status bits can be accessed. This device support is very specific to the Tip810 device, which is why it is not provided as a general-purpose CANbus device support.
The Device Type (DTYP) field of the Binary Input records should be
set to Tip810
for which the hardware address (INP)
field is an Instrument I/O type (INST_IO) and provides addressing
information in the following format:
@busName:signalName
The busName identifies the Tip810 card which is to be monitored, as used for
the other CANbus record types described above.
The signalName element after the :
character should be one of
the following strings which identify the status bit which this record is to
read:
signalName Meaning when Set (1) BUS_OFF Device is disconnected from CANbus BUS_ERROR Messages from this node are being flagged with errors DATA_OVERRUN An incoming message was lost RECEIVING A message is being received RECEIVED A message was received and is available for reading SENDING A message is being transmitted SENT Message was transmitted Ok. OK_TO_SEND Transmit buffer is free to accept another message
I/O Interrupt scanning is not supported by this device support, thus these records should probably be processed periodically to monitor the status of the bus. Note that the BUS_OFF signal may never be seen as the Tip810 driver software automatically resets the CAN chip when it goes into the Bus Off state. If it does appear it probably means that the bus is unterminated or disconnected completely, or that there are no other devices connected on it.