canlib

README

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

Install

• Install libraries and utilities: > go get github.com/buffersandbeer/canlib/...
• Install just the library: > go get github.com/buffersandbeer/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. No special dependencies are required for testing.

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 canlib 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

• func ByteArrayToCanFrame(array []byte, canMessage *RawCanFrame, captureTime int64, capIface string)
• func CaptureCan(canInterface string, canChannel chan<- RawCanFrame, errorChannel chan<- error)
• func CompareRawFrames(frameOne RawCanFrame, frameTwo RawCanFrame) bool
• func CompareRawFramesSimple(frameOne RawCanFrame, frameTwo RawCanFrame) bool
• func CreateRawFrame(targetFrame *RawCanFrame, id uint32, data []byte, eff bool, rtr bool, err bool) error
• func ProcessCanalyzeLog(processed *RawCanFrame, frame string) error
• func ProcessCandump(processed *RawCanFrame, frame string) error
• func ProcessRawCan(processed *ProcessedCanFrame, frame RawCanFrame)
• func ProcessedCanFrameToString(frame ProcessedCanFrame, delimiter string) string
• func RawCanChannelMultiplex(input <-chan RawCanFrame, output ...chan<- RawCanFrame)
• func RawCanFrameToString(frame RawCanFrame, delimiter string) string
• func RawFrameInSlice(frame RawCanFrame, frameSlice []RawCanFrame) bool
• func RawFrameInSliceSimple(frame RawCanFrame, frameSlice []RawCanFrame) bool
• func SendCan(canInterface string, message RawCanFrame) error
• func SendCanConcurrent(canInterface string, canChannel <-chan RawCanFrame, errorChannel chan<- error)
• func SetupCanInterface(canInterface string) (int, error)
• func TimestampToSeconds(timestamp int64) float64
• type ProcessedCanFrame
• type RawCanFrame

Functions

func ByteArrayToCanFrame

func ByteArrayToCanFrame(array []byte, canMessage *RawCanFrame, captureTime int64, capIface string)

ByteArrayToCanFrame converts a byte array containing a CAN packet and converts it into a RawCanFrame

func CaptureCan

func CaptureCan(canInterface string, canChannel chan<- RawCanFrame, errorChannel chan<- error)

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

func CompareRawFrames

func CompareRawFrames(frameOne RawCanFrame, frameTwo RawCanFrame) bool

CompareRawFrames 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 containes 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 RawCanFrame structs that are built with SocketCan's candump output is not supported. Instead use CompareRawFramesSimple instead.

func CompareRawFramesSimple

func CompareRawFramesSimple(frameOne RawCanFrame, frameTwo RawCanFrame) bool

CompareRawFramesSimple takes two RawCanFrames 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 RawCanFrames that are built from SocketCan's candump output.

func CreateRawFrame

func CreateRawFrame(targetFrame *RawCanFrame, id uint32, data []byte, eff bool, rtr bool, err bool) error

CreateRawFrame will take an ID, Data, and Flags to generate a valid RawCanFrame

func ProcessCanalyzeLog

func ProcessCanalyzeLog(processed *RawCanFrame, frame string) error

ProcessCanalyzeLog will take a canalyze/canalyze-dump/can-dump log and parse it into a raw_can_frame

func ProcessCandump

func ProcessCandump(processed *RawCanFrame, frame string) error

ProcessCandump will take a Socketcan/candump log and parse it into a raw_can_frame

func ProcessRawCan

func ProcessRawCan(processed *ProcessedCanFrame, frame RawCanFrame)

ProcessRawCan will process a raw can message to add additional contextual information

func ProcessedCanFrameToString

func ProcessedCanFrameToString(frame ProcessedCanFrame, delimiter string) string

ProcessedCanFrameToString takes a ProcessedCanFrame and formats it based on several parameters

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

func RawCanChannelMultiplex

func RawCanChannelMultiplex(input <-chan RawCanFrame, output ...chan<- RawCanFrame)

RawCanChannelMultiplex will take a RawCanFrame sent into the input channel and relay it to all output channels

func RawCanFrameToString

func RawCanFrameToString(frame RawCanFrame, delimiter string) string

RawCanFrameToString takes a RawCanFrame and makes it look pretty based on several parameters

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

func RawFrameInSlice

func RawFrameInSlice(frame RawCanFrame, frameSlice []RawCanFrame) bool

RawFrameInSlice 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 CompareRawFrames, it is not compatible with RawCanFrames that are built from SocketCan's candump output. Instead, use RawFrameInSliceSimple.

func RawFrameInSliceSimple

func RawFrameInSliceSimple(frame RawCanFrame, frameSlice []RawCanFrame) bool

RawFrameInSliceSimple takes a RawCanFrame and looks to see if it exists within a slice of RawCanFrames using the simple method

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

func SendCan

func SendCan(canInterface string, message RawCanFrame) error

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

func SendCanConcurrent

func SendCanConcurrent(canInterface string, canChannel <-chan RawCanFrame, errorChannel chan<- error)

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

func SetupCanInterface

func SetupCanInterface(canInterface string) (int, error)

SetupCanInterface will set up a CAN file descriptor to be used with sending and recieving CAN message. The function takes a string that specifies the interface to open. It returns an integer file descriptor, and an error.

func TimestampToSeconds

func TimestampToSeconds(timestamp int64) float64

TimestampToSeconds converts the int64 timestamp into a float unix timestamp

Types

type ProcessedCanFrame

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

ProcessedCanFrame represents a CAN packet and additional data about the packet

type RawCanFrame

type RawCanFrame struct {
	OID              uint32 // 32-bit CAN_ID before masks applied
	ID               uint32 // 32 bit CAN_ID + EFF/RTR/ERR
	Dlc              uint8  // Payload length in bytes
	Eff              bool   // Extended frame flag
	Rtr              bool   // Remote transmission request flag
	Err              bool   // Error flag
	Data             []byte // Message Payload
	Timestamp        int64  // Time message was captured as Unix Timestamp in nanoseconds
	CaptureInterface string // Name of capturing interface
}

RawCanFrame represents the data contained in a CAN packet