-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathdevCan.html
372 lines (291 loc) · 14.8 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
367
368
369
370
371
372
<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 software">
<META NAME="KeyWords" CONTENT="CANbus, EPICS, Tip810">
<META NAME="Version" CONTENT="$Id: devCan.html,v 1.5 2002-04-17 19:30:49 anj Exp $">
</HEAD>
<BODY>
<H1 ALIGN=CENTER>devCan - CAN Bus Device Support</H1>
<CENTER><P>Developed for Gemini and UKIRT <BR>
CANbus Device Support for EPICS <BR>
Version 1.1b</P></CENTER>
<CENTER><ADDRESS>Andrew Johnson
<A HREF="mailto:anjohnson@iee.org"><anjohnson@iee.org></A>
</ADDRESS></CENTER>
<UL>
<LI><A HREF="#section1">Introduction</A></LI>
<LI><A HREF="#section2">Common Issues</A></LI>
<UL>
<LI><B>ENHANCED: </B><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><B>CHANGED: </B><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><B>NEW: </B><A HREF="#biTip810">Tip810 Module Status Records</A></LI>
</UL>
<P><HR></P>
<H2><A NAME="section1"></A>1. Introduction</H2>
<P>This document describes the device support provided with the
<A HREF="http://www.gemini.edu/">Gemini</A>/
<A HREF="http://www.jach.hawaii.edu/UKIRT/home.html">UKIRT</A>
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 with version 2 of the driver software 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>
<P><HR></P>
<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 just the Tews TIP810 Industry-Pack
module if a suitable driver is written. </P>
<P>Each record is associated with a single message identifier on a particular
CANbus, although an 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 (<B><TT>DTYP</TT></B>) field set
to "<B><TT>CANbus</TT></B>" for which the hardware address field
(<B><TT>INP</TT></B> or <B><TT>OUT</TT></B>) is an Instrument I/O type
(<B><TT>INST_IO</TT></B>), 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 "<B><TT>@</TT></B>" 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 "<B><TT>/</TT></B>" or "<B><TT>:</TT></B>"
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 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
set a watchdog timer, and if no response is received within the given period
the record is set to the <B><TT>TIMEOUT_ALARM</TT></B> status with a severity
of <B><TT>INVALID_ALARM</TT></B>. </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 <B><TT>SCAN</TT></B> 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 (Bus
Error alarms were disabled in Version 1.1b but have been reinstated in V1.1c).
The alarm status and severity meanings are given in the following table: </P>
<CENTER><TABLE BORDER=1 >
<TR BGCOLOR="#FFFFFF">
<TD><B><I>Status</I></B></TD>
<TD><B><I>Severity</I></B></TD>
<TD><B><I>Description</I></B></TD>
</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></CENTER>
<P><HR></P>
<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 "<B><TT>float</TT></B>" or "<B><TT>double</TT></B>".
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 these formats are 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 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 <B><TT>LINR</TT></B>
field. If this is set to "<B><TT>NO CONVERSION</TT></B>" the record
value will be identical to the raw value read from the CAN message. When set to
"<B><TT>LINEAR</TT></B>" the input range specified by the address
parameter will be mapped directly to the range given by the
<B><TT>EGUL</TT></B> and <B><TT>EGUF</TT></B> fields. This applies even if the
input range is 2s-complement such that the most negative input will give return
the value given by <B><TT>EGUL</TT></B> and the most positive will return
<B><TT>EGUF</TT></B>. </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 <B><TT>NOBT</TT></B> 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 <B><TT>NOBT</TT></B>
exceeds 8. </P>
<P><HR></P>
<H2><A NAME="biTip810"></A>4. Tip810 Module Status Records</H2>
<P>Version 1.1 of the CANbus driver software adds the ability to monitor
the status bits of the Tip810 CANbus interface chip using Binary Input
records. I do not regard these records as necessarily applying to any type
of CANbus interface which is why I have made them specifically named for
the Tip810. The main use of this device support will be for the Bus Status,
Error Status and Data Overrun bits, although all of the status bits can
be accessed. <I>[Note: if there is sufficient demand, the various message
counters could also be made available via the database; at present these
can only be seen by using the t810Report shell command.]</I></P>
<P>The Device Type (<B><TT>DTYP</TT></B>) field of the Binary Input records
should be set to "<B><TT>Tip810</TT></B>" for which the hardware
address (<B><TT>INP</TT></B>) field is an Instrument I/O type
(<B><TT>INST_IO</TT></B>) 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 "<B><TT>:</TT></B>" character
should be one of the following strings which identify the status bit which
this record is to read:</P>
<CENTER><TABLE BORDER=1 >
<TR BGCOLOR="#FFFFFF">
<TD><B><I><TT>signalName</TT></I></B></TD>
<TD><B><I>Meaning when Set (1)</I></B></TD>
</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></CENTER>
<P>I/O Interrupt scanning is not supported by this device support, thus
these records will probably be processed periodically to monitor the status
of the bus. Note that the <B><TT>BUS_OFF</TT></B> 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>
<P><HR></P>
<ADDRESS>Andrew Johnson
<A HREF="mailto:anjohnson@iee.org"><anjohnson@iee.org></A>
</ADDRESS>
</BODY>
</HTML>