Skip to content

Getting Started

This tutorial will guide you through setting up and using Sockcan for the first time.

Installation

Install Sockcan using pip:

pip install sockcan

For development versions:

pip install git+https://github.com/your-repo/sockcan.git

Quick Start

Standalone Usage (Linux with SocketCAN)

The simplest way to use Sockcan on Linux:

from sockcan import SocketcanConfig, connect_to_socketcan, build_send_func, build_recv_func

# Connect to CAN interface
config = SocketcanConfig(channel="vcan0")
sock = connect_to_socketcan(config)

# Build send and receive functions
send_func = build_send_func(sock, expects_msg_cls=False)
recv_func = build_recv_func(sock)

# Send a message
send_func(0x123, b'\x01\x02\x03\x04', False)

# Receive a message
msg = recv_func()
print(f"ID: {msg.arbitration_id:#x}, Data: {msg.data.hex()}")

Setting Up Your CAN Interface

Linux: Virtual CAN (vcan0)

For testing without hardware:

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

Linux: Real CAN Hardware

Connect to a physical CAN interface:

# List available interfaces
ip link show

# Bring up your CAN interface
sudo ip link set up can0

Windows

Windows requires the userspace daemon mode (see Windows Setup).

Two Usage Modes

Sockcan can be used in two different ways:

Mode 1: Standalone

Direct use of Sockcan's API for maximum performance and control.

Best for: - Performance-critical applications - Direct socketcan access on Linux - Applications that don't use python-can

from sockcan import SocketcanConfig, connect_to_socketcan, build_send_func, build_recv_func

config = SocketcanConfig(channel="vcan0")
sock = connect_to_socketcan(config)
send = build_send_func(sock, expects_msg_cls=False)
recv = build_recv_func(sock)

Mode 2: python-can Drop-in Replacement

Use Sockcan as a faster replacement for python-can's socketcan backend.

Best for: - Existing python-can applications - Cross-platform applications - When you want python-can's abstraction layer

import can
from sockcan.interop import hijack_python_can

# Replace python-can's socketcan implementation
hijack_python_can()

# Use python-can as usual
bus = can.Bus(interface="socketcan", channel="can0")
msg = bus.recv()
bus.send(can.Message(arbitration_id=0x123, data=[1, 2, 3, 4]))

Your First Application

Transmitter (sender.py)

from sockcan import SocketcanConfig, connect_to_socketcan, build_send_func
import time

config = SocketcanConfig(channel="vcan0")
sock = connect_to_socketcan(config)
send_func = build_send_func(sock, expects_msg_cls=False)

try:
    counter = 0
    while True:
        data = bytes([counter % 256])
        send_func(0x100, data, False)
        print(f"Sent: ID=0x100, Data={data.hex()}")
        counter += 1
        time.sleep(1)
finally:
    sock.close()

Receiver (receiver.py)

from sockcan import SocketcanConfig, connect_to_socketcan, build_recv_func

config = SocketcanConfig(channel="vcan0")
sock = connect_to_socketcan(config)
recv_func = build_recv_func(sock)

try:
    print("Waiting for messages...")
    while True:
        msg = recv_func()
        print(f"Received: ID={msg.arbitration_id:#x}, Data={msg.data.hex()}")
finally:
    sock.close()

Running the Example

Open two terminals:

# Terminal 1: Start receiver
python receiver.py

# Terminal 2: Start transmitter
python sender.py

You should see messages being transmitted and received in real-time.

Next Steps