UM-0086-A2
CANgate User’s Manual
Page 21
Examples
GPS "GPGLL" 1 D 5000
Receive NMEA-0183 "GPGLL" sentences. Every 5 seconds, return the current degrees component (
-37
for the above input
data)
GPS "GPGSV" 3
When polled, return the number of satellites in view (the third field in a "GPGSV" sentence).
FORMAT Sub-command
As indicated above, all slot definition commands that return a data value may include a
FORMAT
clause to specify how the
data value should be formatted – otherwise the data will be returned in raw hexadecimal form. The format of a
FORMAT
sub-command is as follows:
FORMAT
{ rawFormat }
{ scale
offset }
{
"
formatString
"
}
{ stats }
where:
rawFormat
specifies how the raw bit field is to be interpreted. It consists of two letters, one being
U
or
S
(unsigned or
2's complement signed; default:
U
), the other
M
or
N
(Motorola (MSB first) or Intel (LSB first); default:
M
). Note that for
J1939 memory slots (RECVJ, RQSTJ), Intel format is always used. The byte swapping options are ignored if the size
of the data field is not a multiple of 8 bits.
scale
is a floating point scaling factor which will be multiplied by the raw bit field value (default:
1.0
).
offset
is a floating point offset which will be added to the scaled bit field value (default:
0.0
).
formatString
is a string which specifies: the output type (raw hexadecimal, integer, floating point, string, etc.),
formatting options (eg. number of decimal places) and any leading or trailing text. Default is
"%f\n
" (output floating
point value, 2 decimal places, followed by CRLF) See below for more details.
stats
is a statistical operation (
MIN
,
MAX
or
AVE
). If set, all matching CAN messages are received and processed.
When the slot is polled, the calculated minimum, maximum or average value (since last poll) is returned. If not
specified (which is the default), the most recent instantaneous data value is returned.
Note:
statistical operations are
only valid for passive CAN slot types (RECV, RECVE, RECVJ)
Format String
A format string consists of three text elements:
some text to display before the data value (default: none)
a
conversion specifier
, which begins with a
%
character and specifies the data type (integer, floating point etc.) and
possibly some other formatting details. If no conversion specifier is present (which is the default), the data value will be
output in raw hexadecimal format, exactly as it appears in the CAN message (in this case the
rawFormat
,
scale
,
offset
and
stats
parameters will be ignored.)
some text to display after the data value (default:
\n
). If no conversion specifier is present, all text in the format string
will be returned after the data value.
The format of the conversion specifier is as follows (there are no gaps between the various elements):
%
{ flag } { width }{
.
precision } type
where:
%
marks the start of the conversion specifier
type
is a single character which specifies the data type:
f
(floating point),
d
(signed decimal integer),
u
(unsigned
decimal integer),
x
/
X
(unsigned lower/upper case hexadecimal integer) or
s
(ASCII string)
flag
is a single character which alters the way the other elements work, as described in
width
below (default: none)
width
is an integer, the minimum number of characters to output. If the converted data value is longer than
width
then
all characters will still be output. If the data value is shorter then it will be padded on the left with spaces (or zeroes, if
flag
= '
0
') so that a total of
width
characters are output. If
flag = '
-
' then the data value will instead be padded on the
right with spaces if it is shorter than
width
. The default value for
width
is 0, ie. no padding characters will be inserted.
precision
is an integer which specifies different things depending on the data type. For floating point, it is the number of
digits displayed to the right of the decimal point (default: 2). For integers, it is the minimum number of displayed digits;
if the data value has fewer digits it will be prefixed by zeroes (default: 0). For strings, it is the maximum number of
characters to display, If the data string is longer then it will be truncated (default: no maximum).
Note that following points about format strings:
An integer (
d
/
u
/
x
/
X
) or floating point (
f
) conversion specifier will be ignored if the data field is larger than 32 bits. In
this case the value will be returned in raw hexadecimal format.
Integer or floating point conversion specifiers are ignored for GPS slots. For a GPS slot, all data values are treated as
strings.
