CANlib

Installation

If you're cloning this for the first time, use git clone --recursive to pull all submodules. However, if you already have this repository cloned non-recursively, make sure to run git submodule init and git submodule update.

To generate this library, run main.py in the generator directory with the path to your CAN spec as an argument (e.g. python main.py ../../../can_spec_my18.yml if you're running this from the lib directory in MY18). Make sure to use Python 3. This generates all of the necessary source files that are listed in .gitignore. These files are dependent on the CAN spec. If you want to change one of these files, don't edit them directly, but instead figure out what needs to change in the CAN spec. (If that still doesn't work, edit the generator scripts in generator rather than the generated files.) Source files that aren't ignored aren't generated from the CAN spec, so they can be edited directly.

When compiling, you need to compile with the appropriate CANLIB_ARCH_ defined in order to use the appropriate driver. Included drivers are listed in driver.h.

Writing a CAN spec

The CAN spec should be a YAML file with the following structure:

name: MYwhatever # Name of your CAN specunits: # Any custom units you need to define
- newtonmeter = N * m = J = Nmarchitecture:
arch1:
family: archxparticipation:
can:
buses:
- hardwareBus1
- hardwareBus2
- hardwareBus3arch2:
family: archxparticipation:
can:
buses:
- hardwareBus1
- hardwareBus2computer: # All boards on the car, along with CAN messages they publish and subscribe toboard1:
architecture: arch1participation:
can:
mapping:
symbolicBus0: hardwareBus2symbolicBus1: hardwareBus3publish:
symbolicBus0:
- Msg0symbolicBus1:
- Msg0subscribe:
symbolicBus0:
- Msg2protocol:
can:
bus: # List of CAN buses on the carsymbolicBus0: # All messages on can0baudrate: 500000extended: falseframe:
key: 0x001# Lower CAN IDs have higher priorityperiod: 50ms # optional, only add it if you will use itatom:
atom0:
slice: 0 + 32 # [start index] + [length]type: int32 big # type and endiannessunit: V # optionalatom1:
slice: 32 + 32type: int32 bigunit: VMsg2:
key: 0x002atom:
atom0:
slice: 0 + 2type:
type: int8endianness: bigenum:
ENUM_A: 0x0ENUM_B: 0x1ENUM_C: 0x2ENUM_D: 0x3symbolicBus1:
baudrate: 1000000extended: trueframe:
Msg0:
key: 0x001# Note that lower CAN IDs have higher priorityatom:
atom0:
slice: 0 + 32 # [start index] + [length]type: int32 big # type and endiannessunit: Vatom1:
slice: 32 + 32type: int32 bigunit: V

Once this spec is set up, to add a new message you need to do each of the following:

• Add the message to the list of messages. Using the format like the messages above, specify key, period, (if necessary), and atom. For each atom, add slice, (of the form starting_position + length), type (of the form c_type endianness, or the more expanded version in the enum)
• Update the publish and subscribe fields for the relevant boards. Add the name of your message to the publish list of your board and whichever boards subscribes to it.

Using the library

To use the can library, include the file canlib_<computer.name>.h for whatever computer it will be running on. (Make sure you have initialized CAN at the baudrate specified in your spec.) The follow names will then be exposed:

CANlib_<bus.name>_<frame.name>_T

This is a struct which has fields corresponding to the atoms in the corresponding frame. For example, for Msg0 on symbolic_can_1 above, it would be defined like this:

typedefstruct {
int32_tatom0;
int32_tatom1;
} CANlib_symbolicBus1_Msg0_T;

It will be available for every frame which the board publishes or subscribes to.

void CANlib_send_<bus.name>_<frame.name>_msg(CANlib_<bus.name>_<frame.name>_T *inp)

This function takes a pointer to a struct of the type described in the previous bullet and sends in on the correct CAN bus. It is only available for messages which the board publishes.

CANlib_update_can()

This function polls for any can messages and updates the relevant structs (see the next bullet). Call this periodically to update your inputs. It will only update structs corresponding to messages which a board subscribes to.

extern CANlib_<bus.name>_<frame.name>_T <bus.name>_<frame.name>_inp;

This statement extern declares the struct which will be updated when a frame.name message is received over can. Declare it in your own file and it will be updated whenever you call CANlib_update_can.

CANlib_<bus.name>_<message.name>_<atom.name>_T

This is an enum that includes values of the form <bus.name>_<message.name>_<atom.name>_<value.name> forall value in atom.value. Use this to refer to the type of enums created for enum segments (e.g., Msg2atom1 above).

Other library names

Do not use these structs in code outside of CANlib. This section is internal documentation.

CANlib_<bus.name>_T

This is an enum that includes values of the form <bus.name>_<message.name> forall message in bus.messages.

CANlib_<bus.name>_T CANlib_Identify_<bus.name>(Frame* frame)

Given a pointer to a Frame, returns the appropriate value from <bus.name>_T. It currently identifies messages based on their id. If a message is unknown w.r.t. the spec, it returns CANlib_UNKNOWN_MSG.

void CANlib_Pack_<bus.name>_<message.name>(CANlib_<bus.name>_<message.name>_T* type_in, Frame* can_out)

Given pointers to a message struct and a Frame respectively, unpacks the message contents into the Frame.

void CANlib_Unpack_<bus.name>_<message.name>(Frame *can_in, CANlib_<bus.name>_<message.name>_T *type_out)

Given pointers to a Frame and message struct respectively, unpacks the Frame contents into the message object.

CANlib_<bus.name>_<message.name>_<property> forall property in ["id", "period"]

The CANlib exposes certain properties for each message defined in the spec. Use them in your code with the above expression. There is no guarantee as to whether you learn about it as part of an enum or though a #define.