Skip to content

Latest commit

 

History

History
567 lines (432 loc) · 12.4 KB

README.md

File metadata and controls

567 lines (432 loc) · 12.4 KB

CAN Tools

Enhanced command-line utilities for CAN communication, built on the cansocket library. These tools provide modern replacements for the traditional canutils with advanced features and backward compatibility.

Overview

  • cansend: Enhanced CAN frame sender with batch operations, templates, and advanced timing control
  • candump: Enhanced CAN frame monitor with sophisticated filtering and multiple output formats

Building the Tools

Tools are built automatically with the main project:

# Build all tools
cmake --build build

# Build specific tool
cmake --build build --target cansend
cmake --build build --target candump

# Disable tools build
cmake -DBUILD_TOOLS=OFF ..

Installation

# Install tools to system PATH
sudo cmake --install build --component tools

# Manual installation
sudo cp build/tools/cansend/cansend /usr/local/bin/
sudo cp build/tools/candump/candump /usr/local/bin/

cansend - Enhanced CAN Frame Sender

Modern replacement for canutils' cansend with advanced features for production use.

Basic Usage

# Send single frame (compatible with canutils)
cansend can0 123#DEADBEEF

# Send extended frame
cansend can0 12345678#1122334455667788

# Send RTR frame
cansend can0 123#R8

# Send CAN FD frame
cansend can0 123##1122334455667788

Advanced Features

Repetition and Timing

# Send frame 10 times
cansend can0 123#1122 --repeat 10

# Send with 100ms interval between frames
cansend can0 123#1122 --repeat 5 --interval 100

# Send continuously (Ctrl+C to stop)
cansend can0 123#1122 --continuous --interval 50

# Per-frame timeout control
cansend can0 123#1122 --timeout 200

Batch Operations

# Send frames from file
cansend can0 --batch frames.txt

# Send frames from config file
cansend can0 --config config.conf

# Dry run (validate without sending)
cansend can0 123#1122 --dry-run

Rate Limiting and Performance

# Limit to 100 frames per second
cansend can0 123#1122 --continuous --rate 100

# Verbose output with timing
cansend can0 123#1122 --repeat 10 --verbose

# Use different threading models
cansend can0 123#1122 --threading shared
cansend can0 123#1122 --threading per-thread
cansend can0 123#1122 --threading lock-free

Template System

# Generate common templates
cansend --generate-templates

# List available templates
cansend --list-templates

# Save frame as template
cansend --save-template heartbeat "System heartbeat" 123#0102030405060708

# Use saved template
cansend can0 --template heartbeat

# Show template details
cansend --show-template heartbeat

# Interactive template builder
cansend --interactive

# Import/export templates
cansend --import-templates batch.txt
cansend --export-templates my_templates.txt

File Formats

Batch File Format

# Comments start with #
123#DEADBEEF
456#1122334455667788
789#R8
# Empty lines are ignored

Config File Format

# Configuration file format
frame=123#DEADBEEF
frame=456#1122334455667788
frame=789#R8

Template File Format

# CAN Send Templates
# Format: name=description:frame_string
heartbeat=System heartbeat:123#0102030405060708
diagnostic=Diagnostic request:7DF#0201050000000000

Command Line Options

Option Description Example
--repeat N Send frame N times --repeat 10
--interval MS Milliseconds between frames --interval 100
--timeout MS Timeout per frame --timeout 200
--continuous Send until interrupted --continuous
--verbose Show detailed output --verbose
--dry-run Validate without sending --dry-run
--rate N Max frames per second --rate 100
--threading MODEL Threading model --threading shared
--batch FILE Send from batch file --batch frames.txt
--config FILE Send from config file --config config.conf
--template NAME Use saved template --template heartbeat

Threading Models

Model Description Use Case
none Standard single-threaded Default, simple usage
shared Shared mutex policy Multi-threaded readers
per-thread Per-thread sockets High-performance parallel
lock-free Lock-free queues Ultra-high frequency

Examples

Production Heartbeat

# Send heartbeat every second
cansend can0 100#01020304 --continuous --interval 1000

Diagnostic Session

# Send diagnostic frames with timing
cansend can0 7DF#0201050000000000 --repeat 3 --interval 50 --verbose

Stress Testing

# High-frequency testing
cansend can0 123#DEADBEEF --continuous --rate 1000 --threading lock-free

Template Workflow

# Create and use templates
cansend --save-template test_msg "Test message" 123#AABBCCDD
cansend can0 --template test_msg --repeat 5

candump - Enhanced CAN Frame Monitor

Modern replacement for canutils' candump with advanced filtering and analysis capabilities.

Basic Usage

# Monitor all frames (compatible with canutils)
candump can0

# Monitor multiple interfaces
candump can0 can1 vcan0

# Monitor with timestamps
candump can0 --timestamp absolute

# Monitor with colors
candump can0 --color

Advanced Filtering

ID Filtering

# Filter by ID range
candump can0 --id-range 0x100-0x200

# Include specific IDs
candump can0 --include-ids 0x123,0x456,0x789

# Exclude specific IDs
candump can0 --exclude-ids 0x400-0x4FF

# Traditional canutils style
candump can0,123:7FF,400:700

Data Filtering

# Filter by data pattern (wildcards with ??)
candump can0 --data-pattern "11 22 ?? 44"

# Filter by data range
candump can0 --data-range 0x00-0xFF

# Regex data matching
candump can0 --data-regex "AB.*CD"

# Only frames with changing data
candump can0 --only-changes

Frame Type Filtering

# Only standard frames
candump can0 --only-standard

# Only extended frames
candump can0 --only-extended

# Only RTR frames
candump can0 --only-rtr

# Only error frames
candump can0 --only-error

# Only CAN FD frames
candump can0 --only-canfd

Rate-Based Filtering

# Limit to 10 frames per second per ID
candump can0 --max-rate 10

# Sample every 10th frame
candump can0 --sample-rate 10

# Time window filtering
candump can0 --time-window 9:00-17:00

Output Formats

Pretty Print (Default)

# Human-readable format
candump can0 --format pretty

# With ASCII data representation
candump can0 --ascii

# With interface names
candump can0 --show-interface

JSON Format

# JSON output
candump can0 --format json

# Pretty JSON with timestamps
candump can0 --format json --timestamp absolute --pretty

CSV Format

# CSV output for analysis
candump can0 --format csv

# Custom CSV fields
candump can0 --format csv --fields timestamp,id,data,dlc

Binary Format

# Binary output for high-speed logging
candump can0 --format binary --log can_dump.bin

Logging and Analysis

File Logging

# Log to file
candump can0 --log can_traffic.log

# Log with rotation (100MB files)
candump can0 --log can_traffic.log --rotate-size 100

# Compressed logging
candump can0 --log can_traffic.log.gz --compress

Real-time Statistics

# Show live statistics
candump can0 --stats

# Show bandwidth monitoring
candump can0 --bandwidth

# Show ID histogram
candump can0 --histogram

Interactive Features

# Pause/resume with signals
candump can0 --interactive

# Stop after N frames
candump can0 --count 1000

# Stop after timeout
candump can0 --exit-after 60s

Command Line Options

Basic Options

Option Description Example
--timestamp TYPE Timestamp format --timestamp absolute
--color Colorized output --color
--format FORMAT Output format --format json
--ascii Show ASCII data --ascii
--verbose Verbose output --verbose

Filtering Options

Option Description Example
--id-range RANGE ID range filter --id-range 0x100-0x200
--include-ids IDS Include ID list --include-ids 0x123,0x456
--exclude-ids IDS Exclude ID list --exclude-ids 0x400-0x4FF
--data-pattern PATTERN Data pattern --data-pattern "11 22 ?? 44"
--data-regex REGEX Data regex --data-regex "AB.*CD"
--only-changes Changed data only --only-changes
--max-rate N Max rate per ID --max-rate 10

Output Options

Option Description Example
--log FILE Log to file --log traffic.log
--rotate-size MB Log rotation size --rotate-size 100
--compress Compress logs --compress
--stats Show statistics --stats
--bandwidth Show bandwidth --bandwidth
--count N Stop after N frames --count 1000

Examples

Basic Monitoring

# Monitor with timestamps and colors
candump can0 --timestamp absolute --color --ascii

Diagnostic Monitoring

# Monitor only diagnostic frames
candump can0 --id-range 0x7E0-0x7EF --only-changes --format json

High-Traffic Analysis

# Monitor high-traffic bus with rate limiting
candump can0 --max-rate 50 --stats --histogram

Error Analysis

# Monitor only error frames and changes
candump can0 --only-error --only-changes --verbose --log errors.log

Performance Testing

# Monitor with binary logging for performance
candump can0 --format binary --log perf_test.bin --stats

Production Monitoring

# 24/7 monitoring with log rotation
candump can0 --log production.log --rotate-size 100 --compress --stats

Integration Examples

Bash Scripting

#!/bin/bash
# Monitor specific IDs and alert on changes
candump can0 --include-ids 0x123,0x456 --only-changes --format json | \
    jq -r '.id + ": " + .data' | \
    while read line; do
        echo "$(date): $line" >> alerts.log
    done

Python Integration

import subprocess
import json

# Monitor CAN traffic in Python
proc = subprocess.Popen(
    ['candump', 'can0', '--format', 'json', '--include-ids', '0x123'],
    stdout=subprocess.PIPE,
    text=True
)

for line in proc.stdout:
    frame = json.loads(line)
    print(f"ID: {frame['id']}, Data: {frame['data']}")

Data Analysis

# Export to CSV for analysis
candump can0 --format csv --count 10000 --log analysis.csv

# Import into analysis tools
python -c "
import pandas as pd
df = pd.read_csv('analysis.csv')
print(df.describe())
"

Performance Considerations

High-Frequency Monitoring

# Use binary format for high-speed logging
candump can0 --format binary --log high_speed.bin

# Use rate limiting to prevent overload
candump can0 --max-rate 1000 --threading lock-free

Memory Usage

# Monitor memory usage for long-running captures
candump can0 --stats --log-memory-usage

CPU Usage

# Use efficient filtering to reduce CPU load
candump can0 --include-ids 0x100-0x200 --sample-rate 10

Troubleshooting

Common Issues

# Check interface status
ip link show can0

# Verify permissions
ls -l /dev/can*

# Test with loopback
candump can0 --loopback

Debug Mode

# Enable debug output
candump can0 --debug --verbose

# Show filter statistics
candump can0 --show-filter-stats

Migration from canutils

cansend Migration

# Old canutils syntax (still works)
cansend can0 123#DEADBEEF

# New enhanced syntax
cansend can0 123#DEADBEEF --repeat 10 --verbose

candump Migration

# Old canutils syntax (still works)
candump can0

# New enhanced syntax
candump can0 --format json --only-changes

Feature Mapping

canutils Enhanced Tools Notes
cansend can0 123#11 cansend can0 123#11 Backward compatible
candump can0 candump can0 Backward compatible
candump -t a can0 candump can0 --timestamp absolute New syntax
candump -c can0 candump can0 --color New syntax
candump -l can0 candump can0 --log can0.log Enhanced logging

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

See the main README.md for general contributing guidelines.

License

These tools are part of the cansocket project and are licensed under the Apache 2.0 License.