0
# Command Line Tools
1
2
Complete suite of command-line utilities for CAN bus interaction, including message logging, log file conversion, message replay, bus monitoring, and bus bridging operations.
3
4
## Capabilities
5
6
### Message Logging (can_logger)
7
8
Log CAN messages to various file formats with filtering and configuration options.
9
10
```bash
11
can_logger [options] output_file
12
13
Options:
14
-c, --channel CHANNEL CAN channel (e.g., can0, vcan0)
15
-i, --interface INTERFACE CAN interface (socketcan, vector, etc.)
16
-f, --filter FILTER Message filter (can_id:can_mask:extended)
17
-v, --verbose Verbose output
18
--bitrate BITRATE CAN bitrate
19
--fd Enable CAN FD mode
20
```
21
22
### Message Playback (can_player)
23
24
Replay CAN messages from log files with timing control and loop options.
25
26
```bash
27
can_player [options] input_file
28
29
Options:
30
-c, --channel CHANNEL Output CAN channel
31
-i, --interface INTERFACE Output CAN interface
32
-g, --gap SECONDS Minimum gap between messages
33
-s, --skip SECONDS Skip initial seconds of playback
34
-l, --loop Loop playback continuously
35
--ignore-timestamps Send messages as fast as possible
36
```
37
38
### Message Monitoring (can_viewer)
39
40
Real-time terminal-based CAN message viewer with filtering and statistics.
41
42
```bash
43
can_viewer [options]
44
45
Options:
46
-c, --channel CHANNEL CAN channel to monitor
47
-i, --interface INTERFACE CAN interface
48
-f, --filter FILTER Message filter
49
--decode DBC_FILE DBC file for message decoding
50
--sort-by ID|TIME|COUNT Sort messages by criteria
51
```
52
53
### Log Format Conversion (can_logconvert)
54
55
Convert between different CAN log file formats with filtering options.
56
57
```bash
58
can_logconvert [options] input_file output_file
59
60
Options:
61
-f, --filter FILTER Apply message filter during conversion
62
-s, --start TIME Start time for conversion
63
-e, --end TIME End time for conversion
64
--input-format FORMAT Force input format (auto-detected by default)
65
--output-format FORMAT Force output format (auto-detected by default)
66
```
67
68
### Bus Bridging (can_bridge)
69
70
Bridge messages between different CAN interfaces or channels.
71
72
```bash
73
can_bridge [options]
74
75
Options:
76
--input-channel CHANNEL Input CAN channel
77
--input-interface INTERFACE Input CAN interface
78
--output-channel CHANNEL Output CAN channel
79
--output-interface INTERFACE Output CAN interface
80
-f, --filter FILTER Filter messages to bridge
81
--bidirectional Enable bidirectional bridging
82
```
83
84
## Usage Examples
85
86
### Basic Message Logging
87
88
```bash
89
# Log SocketCAN traffic to BLF file
90
can_logger -i socketcan -c can0 traffic.blf
91
92
# Log with message filtering (only ID 0x123)
93
can_logger -i socketcan -c can0 -f 0x123:0x7FF:false filtered.asc
94
95
# Log CAN FD messages
96
can_logger -i socketcan -c can0 --fd canfd_traffic.blf
97
98
# Log with verbose output
99
can_logger -i socketcan -c can0 -v debug.log
100
```
101
102
### Message Playback
103
104
```bash
105
# Replay messages with original timing
106
can_player -i socketcan -c can1 recorded_traffic.blf
107
108
# Replay as fast as possible
109
can_player -i socketcan -c can1 --ignore-timestamps fast_replay.asc
110
111
# Replay with minimum 1ms gap between messages
112
can_player -i socketcan -c can1 -g 0.001 spaced_replay.log
113
114
# Loop playback continuously
115
can_player -i socketcan -c can1 -l continuous_test.blf
116
117
# Skip first 30 seconds of recording
118
can_player -i socketcan -c can1 -s 30 partial_replay.asc
119
```
120
121
### Real-time Monitoring
122
123
```bash
124
# Basic message monitoring
125
can_viewer -i socketcan -c can0
126
127
# Monitor with message filtering
128
can_viewer -i socketcan -c can0 -f 0x100:0x700:false
129
130
# Monitor with DBC decoding
131
can_viewer -i socketcan -c can0 --decode vehicle.dbc
132
133
# Monitor and sort by message count
134
can_viewer -i socketcan -c can0 --sort-by COUNT
135
```
136
137
### Log File Conversion
138
139
```bash
140
# Convert BLF to ASC format
141
can_logconvert input.blf output.asc
142
143
# Convert with time range filtering
144
can_logconvert --start 10.5 --end 60.0 long_log.blf excerpt.csv
145
146
# Convert specific message IDs only
147
can_logconvert -f 0x123:0x7FF:false full_log.asc filtered.blf
148
149
# Force format specification (if auto-detection fails)
150
can_logconvert --input-format blf --output-format csv data.bin data.csv
151
```
152
153
### Bus Bridging
154
155
```bash
156
# Bridge between SocketCAN and virtual interface
157
can_bridge --input-interface socketcan --input-channel can0 \
158
--output-interface virtual --output-channel test
159
160
# Bidirectional bridge
161
can_bridge --input-interface socketcan --input-channel can0 \
162
--output-interface vector --output-channel 0 \
163
--bidirectional
164
165
# Bridge with message filtering
166
can_bridge --input-interface socketcan --input-channel can0 \
167
--output-interface virtual --output-channel filtered \
168
-f 0x100:0x7F0:false
169
```
170
171
### Advanced Usage Patterns
172
173
```bash
174
# Log while monitoring (using named pipes on Linux)
175
mkfifo can_pipe
176
can_logger -i socketcan -c can0 can_pipe.blf &
177
can_viewer -i socketcan -c can0 &
178
# Both tools will see the same messages
179
180
# Chain operations: record, convert, and replay
181
can_logger -i socketcan -c can0 recording.blf &
182
# ... record for some time, then Ctrl+C
183
can_logconvert recording.blf recording.asc
184
can_player -i virtual -c test recording.asc
185
186
# Compare two CAN buses
187
can_logger -i socketcan -c can0 bus0.log &
188
can_logger -i socketcan -c can1 bus1.log &
189
# ... record, then analyze differences
190
191
# Automated testing workflow
192
#!/bin/bash
193
echo "Starting CAN test sequence..."
194
195
# Start logging
196
can_logger -i virtual -c test test_results.blf &
197
LOGGER_PID=$!
198
199
# Run test sequence
200
can_player -i virtual -c test test_inputs.asc
201
202
# Stop logging
203
kill $LOGGER_PID
204
205
# Convert and analyze
206
can_logconvert test_results.blf test_results.csv
207
echo "Test complete, results in test_results.csv"
208
```
209
210
### Integration with Scripts
211
212
```python
213
import subprocess
214
import time
215
import can
216
217
def automated_can_test():
218
"""Example of integrating CLI tools with Python scripts."""
219
220
# Start logging in background
221
logger_proc = subprocess.Popen([
222
'can_logger', '-i', 'virtual', '-c', 'test', 'test_log.blf'
223
])
224
225
try:
226
# Generate test traffic with Python
227
bus = can.Bus(channel='test', interface='virtual')
228
229
for i in range(100):
230
msg = can.Message(
231
arbitration_id=0x123,
232
data=[i & 0xFF, (i >> 8) & 0xFF]
233
)
234
bus.send(msg)
235
time.sleep(0.01)
236
237
bus.shutdown()
238
239
finally:
240
# Stop logging
241
logger_proc.terminate()
242
logger_proc.wait()
243
244
# Convert log to CSV for analysis
245
subprocess.run([
246
'can_logconvert', 'test_log.blf', 'test_log.csv'
247
])
248
249
print("Test complete, log converted to CSV")
250
251
# Run the test
252
automated_can_test()
253
```
254
255
### Configuration Files
256
257
```bash
258
# Most tools support configuration files
259
# ~/.canrc or /etc/can.conf
260
261
[default]
262
interface = socketcan
263
channel = can0
264
bitrate = 500000
265
266
[logging]
267
format = blf
268
rotation_max_bytes = 100MB
269
270
[viewer]
271
sort_by = count
272
show_timestamp = true
273
decode_dbc = /path/to/standard.dbc
274
```
275
276
### Error Handling and Troubleshooting
277
278
```bash
279
# Check available interfaces
280
python -c "import can; print(can.VALID_INTERFACES)"
281
282
# Test interface availability
283
can_logger -i socketcan -c can0 /dev/null &
284
TEST_PID=$!
285
sleep 1
286
if kill -0 $TEST_PID 2>/dev/null; then
287
echo "SocketCAN interface working"
288
kill $TEST_PID
289
else
290
echo "SocketCAN interface not available"
291
fi
292
293
# Verbose output for debugging
294
can_logger -v -i socketcan -c can0 debug.log
295
296
# List available channels (interface-specific)
297
ip link show type can # For SocketCAN on Linux
298
```
299
300
## Common Options
301
302
All CLI tools support these common options:
303
304
```bash
305
-h, --help Show help message
306
-v, --verbose Enable verbose output
307
-c, --channel CHANNEL CAN channel identifier
308
-i, --interface INTERFACE CAN interface name
309
--version Show version information
310
```
311
312
## Filter Format
313
314
Message filters use the format: `can_id:can_mask:extended`
315
316
```bash
317
# Examples:
318
0x123:0x7FF:false # Exact match for standard ID 0x123
319
0x100:0x700:false # Match IDs 0x100-0x1FF (mask 0x700)
320
0x18000000:0xFF000000:true # Match extended IDs with specific prefix
321
```
322
323
## Exit Codes
324
325
- `0`: Success
326
- `1`: General error
327
- `2`: Invalid arguments
328
- `3`: Interface not available
329
- `4`: File I/O error
330
- `5`: Hardware error
331
332
## Types
333
334
```python { .api }
335
from typing import List, Dict, Any, Optional
336
import argparse
337
338
def add_bus_arguments(parser: argparse.ArgumentParser,
339
filter_arg: bool = False,
340
prefix: Optional[str] = None,
341
group_title: Optional[str] = None) -> None:
342
"""
343
Add common CAN bus arguments to argument parser.
344
345
Parameters:
346
- parser: ArgumentParser to add arguments to
347
- filter_arg: Whether to include filter argument
348
- prefix: Prefix for argument names (for multiple buses)
349
- group_title: Title for argument group
350
"""
351
352
# CLI utility functions
353
def cast_from_string(value: str, dtype: type) -> Any:
354
"""Cast string value to specified type."""
355
356
def _dict2timing(timing_dict: Dict[str, Any]) -> str:
357
"""Convert timing dictionary to string representation."""
358
```