CAN Wrapper Module Usage Guide

Welcome to the CAN Wrapper Module Usage Guide. This guide will walk you through how to use the CAN Wrapper Module with examples.

Overview

The CAN Wrapper Module simplifies CAN message handling on the TSAT satellite by providing an easy-to-use interface that abstracts our custom protocol. Note that the CAN Wrapper Module does not replace HAL's existing CAN interface. Rather, the CAN Wrapper Module wraps the HAL interface with one that's much cleaner, and nicer to use. It does this while automating certain tasks, such as performing timeout event checks. This makes it so that all of our subsystems can seamlessly communicate in a standardized and effective manner.

Since CAN Wrapper Module interfaces with HAL CAN, you must configure CAN in your project before using it. See CAN Wrapper Module Installation Guide

Initialisation

This module uses a flexible callback approach to handle events such as incoming messages and communication errors.

The CANWrapper_InitTypeDef structure contains many settings that tune the module to your needs.

CANWrapper_InitTypeDef wc_init = {
		.node_id = NODE_ADCS,    // your subsystem's unique ID in the CAN network.
		.notify_of_acks = false, // whether to notify you of incoming ACK's.

		.hcan = &hcan1,  // pointer to the CAN peripheral handle.
		.htim = &htim16, // pointer to the timer handle.

		.message_callback = &on_message_received, // called when a new message is polled.
		.error_callback = &on_error_occured;      // called when a communication error occurs.
};

To initialise CAN Wrapper, call CANWrapper_Init with your chosen settings (sometime after MX_CAN#_Init):

CANWrapper_Init(wc_init);

Polling Events

When an event occurs, (such as a new message arrival or a CAN error is detected) CAN Wrapper places it into a queue for later processing. This is to keep interrupt service routines (ISRs) as short as possible.

Because of this design choice, CAN Wrapper will not trigger your callbacks (i.e. message_callback or error_callback) until you've explicitly instructed it to process the queues.

Call CANWrapper_Poll_Messages to process incoming messages, and CANWrapper_Poll_Errors to process errors.

In most cases, putting these function calls in your main loop will work well.

Immediate Mode

If you wish to have full control over the processing of incoming messages, CAN Wrapper offers an Immediate Mode.

In Immediate Mode, messages are directly forwarded to the message_callback on arrival. In this mode, it will be illegal to call CANWrapper_Poll_Messages as there will be no queue to poll.

If you are using RTOS and wish to process messages in an asynchronous task, the recommended approach is to enable Immediate Mode and use the message_callback as a "loading zone" where messages are placed into an RTOS queue to be processed in a dedicated task.

⚠️ Caution: Remember that when you are using Immediate Mode, your message callback is called from within an ISR. This means all contemporary wisdom about ISR-safety applies. Keep processing short, and be weary that your code could be executing during any state of your program (valid or invalid).

To enable Immediate Mode, open your STM32 project, and navigate to Project > Properties > C/C++ Build > Settings > MCU GCC Compiler > Preprocessor. On the right hand panel, click the "Add" button to add the symbol CWM_IMMEDIATE_MODE. This will cause the CAN Wrapper Module to compile in Immediate Mode.

Keep in mind, Immediate Mode only affects the processing of messages, not errors. You must still make regular calls to CANWrapper_Poll_Errors to ensure errors are detected by your program. If you are using RTOS, it's recommended that you create a dedicated task for this purpose that executes at regular time intervals.

Receiving Messages

Here is starter template for a message handling function. Add your specific subsystem's functionality as needed. Note that this code also makes use of the error tracker utility to record errors when they occur. If you wish to use the error tracker you must initialise it first (not shown here).

#include "tuk/can_wrapper.h"
#include "tuk/error_tracker.h"
#include <stdbool.h>

void on_message_received(CANMessage msg, NodeID sender, bool is_ack)
{
	ErrorBuffer error_buffer; // stores command errors.
	ErrorTracker_Push_Buffer(&error_buffer); // push to the top of the buffer stack.

	switch (msg.cmd)
	{
	case CMD_PLD_SET_WELL_LED: // example command.
	{
		// get the command arguments as defined in the command reference.
		uint8_t well_id, power;
		GET_ARG(msg, 0, well_id); // syntax: GET_ARG(msg, byte #, output var)
		GET_ARG(msg, 1, power);

		// perform instructed action.
		LEDs_Set_LED(well_id, power);
		break;
	}
	// ...
	default:
	{
		// unrecognized command.
		PUT_ERROR(ERROR_UNKNOWN_COMMAND, msg.cmd);
		break;
	}
	}

	if (ErrorBuffer_Has_Error(&error_buffer))
	{
		CANMessage error_report;
		error_report.cmd = CMD_CDH_PROCESS_ERROR;
		SET_ARG(error_report, 0, error_buffer); // syntax: SET_ARG(msg, byte #, input var)

		CANWrapper_Transmit(NODE_CDH, &error_report);
	}

	ErrorTracker_Pop_Buffer();
}

🛟 Best Practice: As usual, make sure to have sanity checks in place in all your functions, especially if a function is meant to directly handle data from the CAN bus. You cannot assume the data you are receiving is valid and correct!

Handling Errors

Here is starter template for an error handling function. Currently, the only type of error that is reported is a timeout event.

#include "tuk/can_wrapper.h"

void on_error_occured(CANWrapper_ErrorInfo error_info)
{
	switch (error_info.error)
	{
	case CAN_WRAPPER_ERROR_TIMEOUT:
	{
		// your call to CANWrapper_Transmit failed to invoke an Acknowledge message
		// in your target recipient. Or, the ACK message simply didn't reach you.
		// This was detected as a timeout event.
		// Here you can resolve the issue as appropriate.

		// You may want to run a check to see if it's still a good idea to resend
		// your message.

		// If all is well, you can re-send the message to the intended recipient like so:
		CANWrapper_Transmit(error_info.recipient, &error_info.msg);

		break;
	}
	}
}

⚠️ Note: The error handling functionality is quite bare in this version. It only notifies of timeouts, but there a plenty of other things that can go wrong. Expect improvements in the future.

Additional Examples

Create & Send a CAN Message

#include "tuk/can_wrapper.h"
#include <stdbool.h>

bool Report_PCB_Temp()
{
	uint16_t temp;
	bool success = TMP235_Read_Temp(&temp);
	if (success)
	{
		CANMessage my_msg;
		my_msg.cmd = CMD_CDH_PROCESS_PCB_TEMP;
		SET_ARG(my_msg, 0, temp);
		CANWrapper_Transmit(NODE_CDH, &my_msg);
	}

	return success;
}

🛟 Best Practice: Unless your best judgement says otherwise, favour hard-coding the recipient of a message you are about to send. This reduces the variability of behaviour in your code.

The `CANMessage` Data Members

The CANMessage type has three fields:

.cmd: the command ID
.body: the arguments of the command
.data: the entire message (including command ID & body)

The data field occupies the same section in memory as the other two. Therefore, any change to cmd or body will reflect in data, and vice-versa. Think of msg.data as a shorthand for (uint8_t*)msg. (that is literally what it is)

CANMessage msg;

msg.cmd = CMD_CDH_PROCESS_PCB_TEMP;  // set command ID.
msg.data[0] = CMD_CDH_PROCESS_MCU_TEMP; // another way to set command ID. (less legible)

msg.body[0] = 'A'; // set first byte in message body. (ie. the byte after command ID)
msg.data[1] = 'A'; // equivalent.
SET_ARG(msg, 0, 'A'); // equivalent.

// SET_ARG allows you to assign larger types to the message body very easily.
// Warning: make sure your data is no more than 7 bytes! (56 bits)
uint32_t large_number = 4294967295;
SET_ARG(msg, 0, large_number)

// you can access arguments in a similar way
uint8_t single_byte;
uint32_t four_bytes;
GET_ARG(msg, 0, single_byte); // retrieves byte 0 in the message body.
GET_ARG(msg, 0, four_bytes);  // retrieves bytes 0-3 in the message body.

It is highly encouraged to use the SET_ARG and GET_ARG macros to set and get command arguments since it not only makes your code more human-readable, but it also ensures your code is resilient against future breaking changes to the CANMessage structure in the future.

See can_message.h for the full structure definition.

Tips 'n' Tricks

To quickly search for commands in the code editor, type the name of a prefix (e.g. one of CMD_PLD, CMD_ACDS, CMD_PWR, or CMD_CDH) and press Ctrl + Space. You'll then be greeted with a list of matching commands. (assuming you've included tuk/can_wrapper.h)
If you haven't already, check out the Command Reference for TSAT-7 to read up on the expected format of each command. Ensuring the format you send is correct is important, as otherwise the data received may be incorrect or it might be cut off.

Additional Reading

The below link is old, so I don't recommend reading it, but I will leave it here in case you want to read the documentation for the old version of this interface or you want to understand the high level concepts of how CAN works. Definitely not a required read to use this module.

https://drive.google.com/file/d/1HHNWpN6vo-JKY5VvzY14uecxMsGIISU7/view?usp=share_link

Navigation Menu

Uh oh!

CAN Wrapper Module Usage Guide

Table of Contents

Overview

Initialisation

Polling Events

Immediate Mode

Receiving Messages

Handling Errors

Additional Examples

Create & Send a CAN Message

The `CANMessage` Data Members

Tips 'n' Tricks

Additional Reading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Uh oh!

CAN Wrapper Module Usage Guide

Table of Contents

Overview

Initialisation

Polling Events

Immediate Mode

Receiving Messages

Handling Errors

Additional Examples

Create & Send a CAN Message

The CANMessage Data Members

Tips 'n' Tricks

Additional Reading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

The `CANMessage` Data Members