can

README

CANLIB - A GO library and a series of utilities for CAN bus testing

Install

• Install libraries and utilities: go get github.com/jbreitbart/canlib/...
• Install just the library: go get github.com/jbreitbart/canlib/

Userspace Utilities

• can-dump - Dump CAN packets from SocketCan interface and display extended information
• can-fuzz - Incrementally fuzz CAN messages
• can-halfpipe - Print messages originiating from a target device using a "bump in the wire"

Docs

Documentation and usage explanations for the library can be found at https://godoc.org/github.com/buffersandbeer/canlib.

Tests

go test is used for unit testing. Tests require a vcan interface to be successful:

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

Library Features

• Write to CAN Bus interface
• Read from CAN Bus interface
• Generate CAN messages
• Process CAN messages
• Pretty Print CAN messages

Documentation

Overview

Package can is a GO implementation of several Controller Area Network (CAN) utilities that facilitate the interaction with CAN messages and networks.

It contains functions, structs, and utilities that assist with the capture, processing, generation, and sending of CAN messages that were captured either by the functions in this library, or with other common capture methods such as SocketCan's userspace utilities

Index

• Constants
• func CaptureCan(canInterface InterfaceDescriptor, canChannel chan<- *Frame, ...)
• func ChannelMultiplex(input <-chan *Frame, output ...chan<- *Frame)
• func CloseCanInterface(canInterface InterfaceDescriptor) error
• func CompareFrames(frameOne *Frame, frameTwo *Frame) bool
• func CompareFramesSimple(frameOne *Frame, frameTwo *Frame) bool
• func FrameInSlice(frame *Frame, frameSlice []*Frame) bool
• func FrameInSliceSimple(frame *Frame, frameSlice []*Frame) bool
• func ReceiveNFrames(canInterface InterfaceDescriptor, n int, canChannel chan<- *Frame, ...)
• func SendConcurrent(canInterface InterfaceDescriptor, canChannel <-chan *Frame, ...)
• func SendFrame(canInterface InterfaceDescriptor, message *Frame) error
• func TimestampToSeconds(timestamp int64) float64
• type Frame
  • func CreateFrame(id uint32, data []byte, rtr bool, err bool) (*Frame, error)
  • func CreateFrameFromByte(array []byte, captureTime int64) (*Frame, error)
  • func ReceiveFrame(canInterface InterfaceDescriptor) (*Frame, error)
  • func (frame Frame) Dlc() int
  • func (frame Frame) Eff() bool
  • func (frame Frame) Err() bool
  • func (frame Frame) ID() uint32
  • func (frame Frame) Rtr() bool
  • func (frame Frame) ToString(delimiter string) string
• type InterfaceDescriptor
  • func SetupCanInterface(canInterface string) (InterfaceDescriptor, error)
• type ProcessedFrame
  • func (frame ProcessedFrame) ToString(delimiter string) string
• type Router
  • func NewRouter(canFD InterfaceDescriptor) Router
  • func (r *Router) Stop()
  • func (r *Router) Subscribe(id uint32, ch chan<- *Frame)
  • func (r *Router) Unsubscribe(id uint32, ch chan<- *Frame)

Constants

const ALLIDs = 0xFFFFFFFF

Functions

func CaptureCan

func CaptureCan(canInterface InterfaceDescriptor, canChannel chan<- *Frame, errorChannel chan<- error)

CaptureCan will listen to the provided SocketCAN interface and add any messages seen to the provided channel TODO remove?

func ChannelMultiplex

func ChannelMultiplex(input <-chan *Frame, output ...chan<- *Frame)

ChannelMultiplex will take a Frame sent into the input channel and relay it to all output channels

func CloseCanInterface

func CloseCanInterface(canInterface InterfaceDescriptor) error

CloseCanInterface closes the passed interface

func CompareFrames

func CompareFrames(frameOne *Frame, frameTwo *Frame) bool

CompareFrames takes two Raw Can Frames and returns true if they are the same frame and false otherwise

This comparison is done on all fields and flags except anything time based. Since a Raw Can Frame's OID contains the masked ID and Flags, it is used for comparison to save a bit of computation. Because of this OID comparison, this function is not compatible with Frame structs that are built with SocketCan's candump output is not supported. Instead use CompareFramesSimple instead.

func CompareFramesSimple

func CompareFramesSimple(frameOne *Frame, frameTwo *Frame) bool

CompareFramesSimple takes two Frames and returns true if they are the same frame and false otherwise

This comparison is only performed on the ID, Data Length, and Data Contents. It does not support checking flasgs or masks in order to support Frames that are built from SocketCan's candump output.

func FrameInSlice

func FrameInSlice(frame *Frame, frameSlice []*Frame) bool

FrameInSlice takes a Raw Can Frame and looks to see if it exists within a slice of Raw Can Frames

Because this function makes use of CompareFrames, it is not compatible with Frames that are built from SocketCan's candump output. Instead, use FrameInSliceSimple.

func FrameInSliceSimple

func FrameInSliceSimple(frame *Frame, frameSlice []*Frame) bool

FrameInSliceSimple takes a Frame and looks to see if it exists within a slice of Frames using the simple method

Because this function makes use of CompareFramesSimple, it is compatible with Frames that are built from SocketCan's candump output.

func ReceiveNFrames

func ReceiveNFrames(canInterface InterfaceDescriptor, n int, canChannel chan<- *Frame, errorChannel chan<- error)

ReceiveNFrames reads N frames from the provided interface

func SendConcurrent

func SendConcurrent(canInterface InterfaceDescriptor, canChannel <-chan *Frame, errorChannel chan<- error)

SendConcurrent will utilize a channel to send CAN messages on the given CAN interface

func SendFrame

func SendFrame(canInterface InterfaceDescriptor, message *Frame) error

SendFrame will send the provided CAN message on the given CAN interface

func TimestampToSeconds

func TimestampToSeconds(timestamp int64) float64

TimestampToSeconds converts the int64 timestamp into a float unix timestamp

Types

type Frame

type Frame struct {
	OID       uint32 // 32-bit CAN_ID including masks
	Data      []byte // Message Payload
	Timestamp int64  // Time message was captured as Unix Timestamp in nanoseconds
}

Frame represents the data contained in a CAN packet

func CreateFrame

func CreateFrame(id uint32, data []byte, rtr bool, err bool) (*Frame, error)

CreateFrame will take an ID, Data, and Flags to generate a valid Frame

func CreateFrameFromByte

func CreateFrameFromByte(array []byte, captureTime int64) (*Frame, error)

CreateFrameFromByte will take an byte array and tries to create a can Frame

func ReceiveFrame

func ReceiveFrame(canInterface InterfaceDescriptor) (*Frame, error)

ReceiveFrame reads a frame from the provided interface

func (Frame) Dlc

func (frame Frame) Dlc() int

Dlc returns the length of the data stored in the frame

func (Frame) Eff

func (frame Frame) Eff() bool

Eff returns if this frame is using extended IDs (29bit)

func (Frame) Err

func (frame Frame) Err() bool

Err returns if the frame is an error frame

func (Frame) ID

func (frame Frame) ID() uint32

ID returns the ID of the frame

func (Frame) Rtr

func (frame Frame) Rtr() bool

Rtr returns the remote transmission request bit is set

func (Frame) ToString

func (frame Frame) ToString(delimiter string) string

ToString takes a Frame and makes it look pretty based on several parameters

This function is designed to be used to prepare a Frame for multiple output formats including stdout, csv, and other custom delimited formats.

type InterfaceDescriptor

type InterfaceDescriptor int

InterfaceDescriptor is a can device handler that must be passed to functions using the can bus. Create one with SetupCanInterface.

func SetupCanInterface

func SetupCanInterface(canInterface string) (InterfaceDescriptor, error)

SetupCanInterface will set up a CAN file descriptor to be used with sending and receiving CAN message. The function takes a string that specifies the interface to open.

type ProcessedFrame

type ProcessedFrame struct {
	Packet       Frame  // CAN packet
	PacketHash   string // md5 hash of the Packet's ID and Data fields
	AlphaNumData string // Any Alpha-numeric data within the can payload
}

ProcessedFrame represents a CAN packet and additional data about the packet

func (ProcessedFrame) ToString

func (frame ProcessedFrame) ToString(delimiter string) string

ToString takes a ProcessedFrame and formats it based on several parameters

This function is designed to be used to prepare a Frame for multiple output formats including stdout, csv, and other custom delimited formats.

type Router

type Router struct {
	// contains filtered or unexported fields
}

func NewRouter

func NewRouter(canFD InterfaceDescriptor) Router

NewRouter creates a new router and starts it

func (*Router) Stop

func (r *Router) Stop()

Stop will stop the router and drains all of its channels

func (*Router) Subscribe

func (r *Router) Subscribe(id uint32, ch chan<- *Frame)

Subscribe adds ch to the subscriber list for id

func (*Router) Unsubscribe

func (r *Router) Unsubscribe(id uint32, ch chan<- *Frame)

Unsubscribe removes ch from the subscriber list for id