-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathdevCan.html
366 lines (284 loc) · 14.1 KB
/
devCan.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
<HTML>
<HEAD>
<TITLE>devCan - CAN Bus Device Support</TITLE>
<META NAME="Author" CONTENT="Andrew Johnson" />
<META NAME="Description"
CONTENT="User Documentation for the EPICS CANbus device support" />
<META NAME="KeyWords" CONTENT="CANbus, EPICS, TIP810" />
<META NAME="Version"
CONTENT="$Id$" />
</HEAD>
<BODY>
<H1 ALIGN=CENTER>devCan - CAN Bus Device Support</H1>
<P ALIGN=CENTER>CANbus Device Support for EPICS <BR>
Version 2.9</P>
<P ALIGN=CENTER><I>Andrew Johnson
<A HREF="mailto:anj@aps.anl.gov"><anj@aps.anl.gov></A></I></P>
<H2>Contents</H2>
<UL>
<LI><A HREF="#section1">Introduction</A></LI>
<LI><A HREF="#section2">Common Issues</A></LI>
<UL>
<LI><A HREF="#hardwareAddressing">Hardware Addressing</A></LI>
<LI><A HREF="#asynchronousProcessing">Asynchronous Processing</A></LI>
<LI><A HREF="#recordScanTypes">Record Scan Types</A></LI>
<LI><A HREF="#alarmStatus">Alarm Status</A></LI>
</UL>
<LI><A HREF="#section3">Record-Specific Behaviour</A></LI>
<UL>
<LI><A HREF="#analogueRecords">Analogue Records</A></LI>
<LI><A HREF="#binaryRecords">Binary Records</A></LI>
<LI><A HREF="#multiBitBinaryRecords">Multi-Bit Binary Records</A></LI>
</UL>
<LI><A HREF="#biTip810">Tip810 Module Status Records</A></LI>
</UL>
<HR>
<H2><A NAME="section1"></A>1. Introduction</H2>
<P>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: <A HREF="drvTip810.html">drvTip810 - CAN Bus Driver</A>
and <A HREF="drvIpac.html">drvIpac - Industry Pack Driver</A>.</P>
<P>Device Support routines have been provided for the following record
types:</P>
<UL>
<LI>Analogue Records (ai, ao)</LI>
<LI>Binary Records (bi, bo)</LI>
<LI>Multi-Bit Binary Records (mbbi, mbbo)</LI>
<LI>Multi-Bit Binary Direct Records (mbbiDirect, mbboDirect)</LI>
</UL>
<P>The device support behaviour for these record types is substantially
the same. The differences are discussed individually for each record type
in <A HREF="#section3">section 3</A> below.</P>
<P>Also available is the ability to check the status of the Tip810 CANbus
interface, using:</P>
<UL>
<LI>Binary Input Records to access the TIP810 module status (bi)</LI>
</UL>
<P>The support for this record type is significantly different to the others
so is described seperately in <A HREF="#biTip810">section 4</A>.</P>
<HR>
<H2><A NAME="section2"></A>2. Common Issues</H2>
<P>All communication with the CANbus hardware is performed using the routines
defined in the generic header file <I>canBus.h</I>, 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.</P>
<P>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.</P>
<H3><A NAME="hardwareAddressing"></A>Hardware Addressing</H3>
<P>Records should have their Device Type (<TT>DTYP</TT>) field set
to <Q><TT>CANbus</TT></Q> for which the hardware address field
(<TT>INP</TT> or <TT>OUT</TT>) is an Instrument I/O type
(<TT>INST_IO</TT>), which provides for a single address string.
This contains a number of elements, some of which are optional, and is
formatted as follows:</P>
<UL>
<PRE><B>@</B><I>busName</I>[<B>/</B><I>timeout</I>]<B>:</B><I>identifier</I>[<B>+</B><I>n</I>..][<B>.</B><I>offset</I>]<I>parameter</I></PRE>
</UL>
<P>The first element after the <Q><TT>@</TT></Q> 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
<Q><TT>/</TT></Q> or <Q><TT>:</TT></Q> character in the string.</P>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>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 <A HREF="#section3">below</A>).</P>
<H3><A NAME="asynchronousProcessing"></A>Asynchronous Processing</H3>
<P>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 <TT>TIMEOUT_ALARM</TT> status with a
severity of <TT>INVALID_ALARM</TT>.</P>
<H3><A NAME="recordScanTypes"></A>Record Scan Types</H3>
<P>The CANbus messages handled and generated by the device support routines
depend on the setting of the <TT>SCAN</TT> 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.</P>
<P>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.</P>
<P>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.</P>
<H3><A NAME="alarmStatus"></A>Alarm Status</H3>
<P>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:</P>
<BLOCKQUOTE><TABLE BORDER=1>
<TR BGCOLOR="#FFFFFF">
<TH>Status</TH>
<TH>Severity</TH>
<TH>Description</TH>
</TR>
<TR>
<TD><TT>COMM_ALARM</TT></TD>
<TD><TT>INVALID_ALARM</TT></TD>
<TD>CAN Bus Error or Bus Off event</TD>
</TR>
<TR>
<TD><TT>TIMEOUT_ALARM</TT></TD>
<TD><TT>INVALID_ALARM</TT></TD>
<TD>Device or RTR Timeout</TD>
</TR>
<TR>
<TD><TT>UDF_ALARM</TT></TD>
<TD><TT>INVALID_ALARM</TT></TD>
<TD>Internal Error</TD>
</TR>
</TABLE></BLOCKQUOTE>
<HR>
<H2><A NAME="section3"></A>3. Record-Specific Behaviour</H2>
<P>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.</P>
<H3><A NAME="analogueRecords"></A>Analogue Records</H3>
<P>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 <Q><TT>float</TT></Q> or <Q><TT>double</TT></Q>.
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.</P>
<P>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).</P>
<P>Analogue records include the ability to perform an automatic engineering
units conversion, depending on the setting of the record's <TT>LINR</TT>
field. If this is set to <Q><TT>NO CONVERSION</TT></Q> the record
value will be identical to the raw value read from the CAN message. When set to
<Q><TT>LINEAR</TT></Q> the input range specified by the address
parameter will be mapped directly to the range given by the
<TT>EGUL</TT> and <TT>EGUF</TT> fields. This applies even if the
input range is 2s-complement such that the most negative input will give return
the value given by <TT>EGUL</TT> and the most positive will return
<TT>EGUF</TT>.</P>
<H3><A NAME="binaryRecords"></A>Binary Records</H3>
<P>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.</P>
<H3><A NAME="multiBitBinaryRecords"></A>Multi-Bit Binary Records</H3>
<P>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 <TT>NOBT</TT> 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 <TT>NOBT</TT> exceeds 8.</P>
<HR>
<H2><A NAME="biTip810"></A>4. Tip810 Module Status Records</H2>
<P>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.</P>
<P>The Device Type (<TT>DTYP</TT>) field of the Binary Input records should be
set to <Q><TT>Tip810</TT></Q> for which the hardware address (<TT>INP</TT>)
field is an Instrument I/O type (<TT>INST_IO</TT>) and provides addressing
information in the following format:</P>
<UL>
<PRE><B>@</B><I>busName</I><B>:</B><I>signalName</I></PRE>
</UL>
<P>The busName identifies the Tip810 card which is to be monitored, as used for
the other CANbus record types described <A HREF="#hardwareAddressing">above</A>.
The signalName element after the <Q><TT>:</TT></Q> character should be one of
the following strings which identify the status bit which this record is to
read:</P>
<BLOCKQUOTE><TABLE BORDER=1 >
<TR BGCOLOR="#FFFFFF">
<TH>signalName</TH>
<TH>Meaning when Set (1)</TH>
</TR>
<TR>
<TD><TT>BUS_OFF</TT></TD>
<TD>Device is disconnected from CANbus</TD>
</TR>
<TR>
<TD><TT>BUS_ERROR</TT></TD>
<TD>Messages from this node are being flagged with errors</TD>
</TR>
<TR>
<TD><TT>DATA_OVERRUN</TT></TD>
<TD>An incoming message was lost</TD>
</TR>
<TR>
<TD><TT>RECEIVING</TT></TD>
<TD>A message is being received</TD>
</TR>
<TR>
<TD><TT>RECEIVED</TT></TD>
<TD>A message was received and is available for reading</TD>
</TR>
<TR>
<TD><TT>SENDING</TT></TD>
<TD>A message is being transmitted</TD>
</TR>
<TR>
<TD><TT>SENT</TT></TD>
<TD>Message was transmitted Ok.</TD>
</TR>
<TR>
<TD><TT>OK_TO_SEND</TT></TD>
<TD>Transmit buffer is free to accept another message</TD>
</TR>
</TABLE></BLOCKQUOTE>
<P>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 <TT>BUS_OFF</TT> 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.</P>
<HR>
<ADDRESS>Andrew Johnson
<A HREF="mailto:anj@aps.anl.gov"><anj@aps.anl.gov></A>
</ADDRESS>
</BODY>
</HTML>