ECU

Custom ECU for Bespoke Electric Vehicles (EVs)

An open source reference hardware and software for building a custom ECU, designed with bespoke EVs in mind.

The ECU design is particularly tailored to FSAE/Formula Student, custom go-karts, and custom hill-climb vehicles.

Cloning

This project uses submodules. Be sure to fetch submodules when cloning and pulling.

git clone <URL> --recurse-submodules

or

git pull --recurse-submodules

Directory Structure

• firmware Firmware capable of running on the reference hardware.
• hardware Reference hardware design.
• tools Tools used to support operating the ECU.

For more information on sub-components, view the README in the appropriate sub-directory.

General Notes

• The software implementation contains a state machine, fault monitoring, and throttle mapping that may not be suitable for all applications and may need changing before use. These can be found at firmware/src/vcu/vehicleLogic.
• The ECU is also designed to be connected to specific inverter and BMS systems (Cascadia Motion Systems and OrionBMS models).
  • Drivers for these are located at firmware/src/vcu/device.
  • The hardware is designed to be flexible around the use of these devices, as they connect via CAN bus and GPIO pins.
  • The vehicle interface software layer (firmware/src/vcu/vehicleInterface) is designed to allow the drivers to be easily replaced without requiring re-work of the vehicle logic components.
  • firmware/src/vcu/startup/initialize.c dictates what software components are started in run-time.

Detailed Description

Below are detailed descriptions on the ECU hardware and firmware. They are also avilable as dedicated docs in hardware/README.md and firmware/README.md.

• Detailed Hardware Description
• Detailed Firmware Description

[blocked]hardware/README.md

1. Description
2. Top Level System
3. ECU Housing With Loom Connections
4. Detailed Block Diagram
5. PCBA
6. ECU Housing
7. PCB Fab
8. Schematic
9. PCB Layout
10. ECU External Pinout
11. Internal Microcontroller Pinout

Description

The ECU hardware provides a unified solution for several circuits required for a custom EV build:

• A multi-channel power distribution module (PDM)
  • 6 channel
  • 24V
  • Two separate always-on 5V outputs
• An integrated shutdown circuit (SDC)
  • A set of serial normally open relays where any one input failing will cause the circuit to open
• ECU logic and IO unit
  • STM32 microcontroller for logical control
  • Connection ready IO:
    • 3 CAN bus
    • 7 24V GPIO inputs
      • 2x wheel speed, 4x SDC input, dashboard button
    • 4 5V ADC inputs
      • 2x accelerator pedal, 2x brake pressure
    • LED driver
    • 8 configurable 5V GPIO/ADCs
    • RS232 debug connection
    • RS232 spare unpinned connection

Top Level System

ECU Housing With Loom Connections

Detailed Block Diagram

PCBA

ECU Housing

PCB Fab

Non-assembled PCBs.

Schematic

View ECU_Schematic_Print.pdf for the schematic PDF print.

PCB Layout

The PCB is laid out in 4 layers:

1. Components and signal routing
2. Ground
3. 3V3
4. Signal routing

Combined	Layer 1	Layer 2	Layer 3	Layer 4

ECU External Pinout

Internal Microcontroller Pinout

Pin assignments for the internal STM32F7 microcontroller

[blocked]firmware/README.md

Description

The ECU is responsible for overseeing the vehicle state and controlling the vehicle's operation from driver input and operating all devices associated with this process.

The ECU software implements:

• Vehicle logic:
  • Vehicle State Machine
  • Torque controller (torque mapping to control inverter)
  • Fault and safety monitoring
  • Parameter configuration
• Drivers for connected devices and sensors:
  • Inverter/motor controller
  • Battery Management System (BMS)
  • Analog sensors (throttle/brake pedals)
  • Wheel speed sensors
  • Dashboard
• Drivers for peripheral interfaces:
  • Standard interfaces: CAN, I2C, SPI, UART, ADC, GPIO, RTC, CRC
  • Task timer
  • Logging
  • init-time dependency checking
  • EEPROM

Dependencies

• Third-party:
  • FreeRTOS
  • STM32 HAL
  • Unity (C Unit Test framework)

Table of Contents

1. Description
   1. Dependencies
2. Table of Contents
3. Architecture
4. Directory structure
5. Tests
6. Software Components
   1. User Journeys - Internal Operation Examples
      1. Starting vehicle & moving into drive state
      2. Applying torque from throttle pedal
   2. RTOS Tasks and Priorities
7. Software Components Detail
   1. System Init Layer
      1. Init
      2. Global Interrupt Handler
   2. Vehicle Logic
      1. Vehicle State Manager
         1. Vehicle State
         2. Fault Monitoring
            1. LV System Faults
            2. Drive Faults
            3. Special Faults
      2. Soft Watchdog
      3. Throttle Controller
      4. Data Logging
   3. Vehicle Interface
      1. System Configuration
      2. Vehicle Control
      3. Vehicle State
   4. Device Driver Layer
      1. Inverter
      2. BMS
      3. Discrete Sensors
      4. Wheel Speed
      5. PC Interface
         1. Frame Format
         2. Byte Description
         3. Address Names
         4. Messages Types
            1. State Broadcast
            2. Log Message
            3. Debug Console Message (PC to ECU)
      6. IMU
      7. Dashboard output
   5. Peripheral Driver/Lib Layer
      1. CAN
      2. I2C
      3. SPI
      4. UART
      5. ADC
      6. GPIO
      7. RTC
      8. Task Timer
      9. CRC
      10. Logging
      11. Depends
   6. STM32 HAL

Architecture

The firmware is comprised of the following layers:

1. Vehicle Logic
   Implements vehicle behavior including state management and vehicle controls.
2. Vehicle Interface
   Interfacing layer between the vehicle logic and device drivers.
   Device drivers will push data to the vehicle state, which can be pulled by vehicle logic processes. Conversely, vehicle logic processes can control the vehicle in a driver agonstic manner by using the vehicle interface layer. The vehicle interface layer will hide the driver details from the logic layer.
3. Device Drivers
   Implements drivers for off-board devices (e.g. inverter, wheel speed), and on-board ECU specific devices (e.g. IMU, GPS, but not peripherals such as CAN or SPI). These are ECU/vehicle specific devices.
4. Peripheral Drivers
   Implements interfaces to common STM32 peripherals. These drivers interface to the FreeRTOS scheduling enviornment, but are otherwise agnostic to the vehicle related purpose of the ECU, and can act as generalist library. The main purpose of many of these are to provide a thread-safe manner of queueing instructions to lower level peripherals, and handling interrupts where a peripheral may be used by several device drivers.
5. STM32 HAL
   Standard HAL package provided by ST Micro.

Visualized:

Directory structure

• doc Supporting assets for docs
• src
  • vcu Firmware specific to vehicle control unit.
  • system-lib Symlink to common MCU firmware.
  • hal STM32 HAL.
• test VCU tests (overlayed on top of system-lib tests)

Tests

The library is tested via a suite of unit tests contained under test. These unit tests leverge the unit testing framework, Unity.

The tests can be executed by invoking run_tests.sh

Executing the tests will generate a code coverage report using lcov.

This will also invoke the unit tests from evfirmware-lib (System/)

Software Components

Expanding on the high level firmware stack from above, we can see all the software components:

User Journeys - Internal Operation Examples

To visualize the flow of data through this system, we can consider a few examples:

Starting vehicle & moving into drive state

The driver will:

1. Turn power on
2. Press brake, then simultaneously press dashboard button

The ECU firmware will, internally:

1. Power on
   1. Upon powering on, the init code will initialize all code modules.
   2. Devices will report their status to the vehicle state module.
   3. The vehicle state manager will query these fields until it is satisfied that the vehicle is in an idle, ready, and non fault state.
   4. When it transitions to this ready state, it instructs the vehicle control module to flash in a manner that indicates this state.
   5. The vehicle control module relays this requrest to the dashboard output.
   6. The state machine should be in the correct state now, and the driver is shown this state.
2. Driver moves vehicle into drive
   1. The driver physically presses the brake and dashboard button.
   2. At a specific polling period, the discrete sensors module is recording the ADC measurements from the brake sensor ADC input, and the dashboard button input. These measurements are regularly being updated in the vehicle state.
   3. Simultaneously, the vehicle state manager is monitoring vehicle state for these fields. If the brake pressure is appropriately high, and the dashboard button has been simultaneously pressed, the vehicle state manager will move through it's drive train power on process (more details in the vehicle state manager doc), and if successful, will transition to the drive state. While transitioning, it instructs the vehicle control module on what it needs the drive train to be doing.
   4. Once in the drive state, the vehicle state manager will instruct the vehicle control module to indicate on the dashboard that the car is in drive. This invokes a method in dashboard output to update the indicator LED.

Applying torque from throttle pedal

Once the driver puts the vehicle into it's drive state (as above), then pressing the accelerator should apply power to the wheels.

The process internal to the ECU:

• At a regular periodic interval, the discrete sense module will sample all of the ADC input sensors, including the throttle pedal sensors.
  • The sensor values are averaged. If no fault condition is found (i.e. the sensors disagree), the discrete sense module will push the latest sensor value to the vehicle state module.
• Simultaneously, the vehicle control state will:
  1. Periodically (the task nominally runs at 100Hz/10ms) request the latest throttle sensor value. The vehicle control task and sensor tasks run at the same rate. The sensors have a higher priority, so the RTOS should execute sensors first. The sensor field in vehicle state is protected via a mutex.
  2. With the latest throttle sensor value, the throttle control module applies a torque mapping, converting the pedal depression percentage to a requested inverter torque in Nm.
  3. The throttle control module invokes the vehicle contorl module to apply this value of Nm to the drive train.
  4. The vehicle control will then invoke the inverter driver to send a request for this value of torque.
  5. The inverter driver constructs a CAN bus message for the requested torque output, and sends it.
• Simultaneously, the vehicle state manager is monitoring the vehicle state for any fault conditions or requested state changes.

To visualize this flow of data needed by the vehicle control module:

RTOS Tasks and Priorities

The modules with RTOS tasks are arranged into the following priorities.

The RTOS (FreeRTOS) uses preemption and task priorities, and round robin scheduling for equal priorities. Only modules that have RTOS tasks are shown here. The remaining drivers are invoked within an existing task context.

The priorities are selected to achieve:

• Initialization is performed first, and at a higher priority than any other tasks that are started during init.
  This requires the init task to have the highest priority.
• We want the latest sensor data available for the logical tasks. This gives us the desire to have Prio(RT critical sensors) > Prio(RT critical logic).
• We want real-time critical processes to have a high priority. The system performs RT critical work (i.e. driving the vehicle) alongside non-RT critical work (i.e. logging, or checking the PC interface). The RT critical work should always be performed ahead of other work, and non-RT critical work can fill the idle time in-between (most RT critical work is done at 10ms intervals, so the time after RT work has completed until the next 10ms step is available).
• The purpose of the soft watchdog is to capture a fault or hang in a critical task. All critical tasks regularly report to the soft watchdog. It is desirable to place the watchdog task as Prio(soft watchdog) > Prio(all RT critical code) such that:
  • Upon correct operation, the watchdog runs nominally in line with RT critical code.
  • Upon a single task having a fault where it hangs, the scheduler will context switch to the soft watchdog, whose internal counter will identify a fault.
  • If the fault causes the entire system (including scheduler) to lock up, the hardware watchdog will take over.
• Non RT critical tasks can be arranged on lower priorities.
  • Non RT critical sensors (useful for log data) are put on a higher priority than the log task for the same reason as above with the RT critical sensors/logic.

These priorities, in conjunction with the scheduler, enact the following de facto state machine:

This state machine is not explicitly coded as a state machine in the source, it is deliberate emergent behavior of the scheduler.

All critical logic registers with the watchdog handler. The watchdog handler will trigger a system fault if any critical logic is not handled in a timely manner.

Software Components Detail

System Init Layer

Init

As the name suggests, this module is responsible for calling the init method of all other required modules in the system, and doing so in the correct order.

The init module maintains local ownership of the data structures required for all devices. It does not expose them in the global context.

The init module will create an init task, where all initialization methods are invoked from. Many init methods (for other modules) will create further RTOS tasks. Upon init completion, the init task will be deleted, however the data storage will remain.

Global Interrupt Handler

This is really a sub-component of the init module, but broken out explicitly for clairty. Certain higher level drivers require some code to run from an interrupt handler. In some instances, the timing and frequency of these events would prohibit this from being done via RTOS task notifications (for example, the wheel speed sensors may run at several kHz, but perform very simple code for each ISR routine). The global interrupt handler simply implements the ISR routine, and calls each module's ISR as needed.

Vehicle Logic

Vehicle State Manager

The Vehicle State Manager is responsible for two tasks:

• Managing the vehicle state
• Monitoring fault conditions (and handling them)

Vehicle State

The state diagram essentially follows:

1. Power up and wait for external devices to power up/become ready.
2. At user request, engage HV system and wait for HV to become ready.
3. Switch between driving states at user request.
4. Or enter fault state from any of the above if a fault is observed.

As noted in the diagram, there is no reverse drive state due to hill-climb/FSAE/etc vehicles having no rear visibility & no need to move in reverse.

Fault Monitoring

Faults are split into two categories: Drive Faults and LV System Faults.

• Drive faults will always invoke a transition to the fault state, regardless of origin state.
• LV System faults will only invoke a transition to the fault state only from the LV ready state and onwards. Earlier during init (i.e. LV startup state), it is assumed that the LV systems may be in unsable states as they are initializing. After LV startup, all critical systems must remain in a known good state.

All faults are encoded into an error value. They are encoded as a binary one-hot system (i.e. individual faults are all a power of 2) such that multiple errors can be expressed as a logical OR of their individual error codes. Fault codes are encoded as a 32-bit word. LV System Faults occupy the lower 8 bits and Drive Faults oppupy top 24 bits.

LV System Faults

Drive Faults

Special Faults

A number of scenarios require more extreme management of a fault:

• A CPU fault
  The code is configured to handle CPU faults (with a custom CPU hard fault handler).
• A hardware watchdog timeout
  There is a hardware watchdog in use in addition to the soft watchdog.
  The hard watchdog will catch more extreme system hangs where the soft watchdog or RTOS scheduler has hung
• A microcontroller brown-out
• The vehicle state manager has transitioned into a fault state, but peripherals indicate that they are still in fault state
• A soft watchdog has been triggered, but the vehicle state manager has not transitioned to it's fault state.

If these occur, the firmware will immeidately run a special fault handler where it moves the vehicle into a safe state by:

• Powering off inverter power channel
• Enabling the ECU fault output (this will open the SDC relays)
• Apply a solid LED output to indicate that the ECU is stuck
• Hold in an infinite loop - we no longer proceeed past this point.

These operations are done with as little firmware layers as possible - they will write directly to hardware (i.e. they bypass the Vehicle Control component, and the drivers below this, as it is likely unclear what has caused this fault).

Soft Watchdog

The soft watchdog is an indepent RTOS task where, during init, other critical tasks will register to the soft watchdog. During runtime, these critical tasks must "feed" the watchdog (just call a notification task to reset their respective counters). The watchdog will count how long it has been since a feed from each critical task. If the count exceeds a timeout, it will update a flag in the vehicle state, where the state machine manager component will read this and act accordingly.

The soft watchdog will monitor the vehicle state. If a fault state is not entered within a small amount of time, the special fault handler will be invoked.

The soft watchdog task is also responsible for feeding the hardware watchdog. The soft watchdog should be able to account for all faults that don't prevent the task from running, which is where the hardware watchdog will take over (and run the special fault handler).

Throttle Controller

This module will read the throttle pedal sensor value, translate this via a torque map to a request of Nm, and requests this from the inverter. This operation (or whether the module sits idle) is controlled via the API, and is called by the vehicle state manager.

The module contains a torque map. The exact torque value is found by linearly interpolating between entries of the torque map.

The torque map implemented is:

• The configured torque is based on a motor with a maximum torque of 500 Nm.
• A deadzone of 0 Nm is created between 0 and 10% pedal depression. To account for very light movement and ADC noise, a deadzone is applied.
• To allow for more precise control at slower speeds, the output torque up to 50% pressed is fairly limited.
• If the driver wants to accelerate rapidly, the torque increases rapidly after this point.

Single pedal driving and regenerative braking are currently not supported. Only mechanical braking is supported.

Any regenerative braking would be added to this module, however.

Data Logging

The data logging module simply makes a copy of system state and logs it to a file on the SDMMC at on a regular periodic interval.

Vehicle Interface

System Configuration

Note: The system configuration as described here is is not currently implemented. The code currently implements a default config data structure.

The system configuration is a table of values used by the rest of the system during init. The table is populated by fields stored on the extermal EEPROM.

Configuration options include the pedal calibration, or fault timeout periods. The full list of configurations are available in firmware/src/vcu/vehicleInterface/config/configData.h.

Configuration values are stored on the 256Kbit (32KiB) EEPROM. To simplify development and modification, the external EEPROM is loaded with an instance of littlefs. The configuration items are stored as files under /config/. Their paths represent the field values and the file contents are the configuration value. Each file has a corresponding *.crc32 checksum file.

E.g. for the calibration of accelerator pedal sensor A, the files are:

• /config/inputs/accelPedal/calibrationA/rawLower Raw ADC value corresponding to the pedal being 0% pressed.
• /config/inputs/accelPedal/calibrationA/rawLower.crc32 32-bit CRC of rawLower
• /config/inputs/accelPedal/calibrationA/rawUpper Raw ADC value corresponding to the pedal being fully pressed.
• /config/inputs/accelPedal/calibrationA/rawUpper.crc32 32-bit CRC of rawUpper

The PC interface can also query and update the values on the EEPROM, but they are only loaded into the system configuration module at startup.

Vehicle Control

The Vehicle Control module is really just a shim. It contains APIs that allow control over any aspect of the car. Internally, it will just invoke one of the device drivers to achieve the requested funtionality.

Current operations supported:

• Enable inverter
• Disable inverter
• Request motor torque - set torque in Nm and motion direction
• Set power channel - set power channel number and enable/disable
• Set ECU error - set to enabled or disabled
• Set dash LED output - set to on or off

Vehicle State

The vehicle state module holds the current physical state of the car and owns the sychronization primitives controlling thread-safe access to these variables.

You can safely copy the state by invoking VehicleState_CopyState. Alternatively, individual elements can be accessed by using VehicleState_AccessAcquire and then reading or writing values. VehicleState_AccessRelease must always be used after a successful acquire.

The vehicle state is conceuptialized as a tree, and currently contains:

• Input sensors
  • Averaged accelerator input [0.0 - 1.1]
  • Accelerator A input [0.0 - 1.1]
  • Accelerator B input [0.0 - 1.1]
  • Accelerator A raw ADC reading
  • Accelerator B raw ADC reading
  • Accelerator valid [bool]
• Dash inputs
  • Dash button pressed [bool]
• Vehicle sensors
  • GPS
    • UTC Time
    • Latitude
    • Longitude
    • Position fix?
    • Number of satellites
  • SDC
    • BMS fault state [bool, true = fault condition]
    • BSPD fault state
    • IMD fault state
    • ECU fault output active
  • Wheel speed
    • Wheel speed front (RPM)
    • Wheel speed rear (RPM)
    • Wheel speed front count
    • Wheel speed rear count
• GLV state
  • PDM channel state 1-8 [bool, true = power enabled]
• Battery state
  • Maximum cell voltage [Volts]
  • Maximum cell voltage - Cell ID
  • Maximum cell temperature [Celsius]
  • Maximum cell temperature - Cell ID
  • Minimum cell voltage [Volts]
  • Minimum cell voltage - Cell ID
  • Minimum cell temperature [Celsius]
  • Minimum cell temperature - Cell ID
  • DC Current [Amps]
  • DC Voltage [Volts]
  • BMS Fault indicator [bool]
  • BMS number of populated cells
  • BMS message counter
  • BMS failsafe status
• Motor
  • Temperature [Celsius]
  • Angle [Degrees]
  • Speed [rpm]
  • Phase A current [Amps]
  • Phase B current [Amps]
  • Phase C current [Amps]
  • Calculated torque [Nm]
• Inverter
  • Module A temperature [Celsius]
  • Module B temperature [Celsius]
  • Module C temperature [Celsius]
  • Gate driver temperature [Celsius]
  • Control board temperature [Celsius]
  • Output frequency [Hz]
  • DC bus current [Amps]
  • DC bus voltage [Amps]
  • Output voltage [Line-neutral voltage]
  • D-axis voltage [Volts]
  • Q-axis voltage [Volts]
  • Commanded flux [Wb]
  • Feedback flux [Wb]
  • D-axis current feedback [Amps]
  • Q-axis current feedback [Amps]
  • D-axis commanded current [Amps]
  • Q-axis commanded current [Amps]
  • Commanded torque [Nm]
  • Modulation index
  • Flux weakening output [Amps]
  • Inverter VSM state
  • Inverter state
  • Discharge state
  • Inverter enabled [bool]
  • Motion direction
  • Timer counts (incremented every 3ms)
  • Run faults (inverter fault codes)
  • Post fault (inverter fault codes)

Device Driver Layer

Inverter

This module will handle CAN bus messages from the inverter, updating the state machine, and will construct CAN bus messages to send to the inverter based on the driver API.

The inverter driver is based a Cascadia Motion Sytems CM200 inverter.

BMS

This module will handle CAN bus messages from the inverter, updating the state machine.

The BMS driver is based on an OrionBMS 2 with the following CAN message configuration:

All fields size >1 byte are sent LSB first.

Data Formats:

Discrete Sensors

This module perodically reads discrete sensors (GPIO inputs and ADC inputs) and pushes the results to the vehicle state.

This module currently handles:

• Accelerator pedal A
• Accelerator pedal B
• Average accelerator pedal
• Brake pressure front
• Brake pressure rear
• Bashboard button

The module updates these values on a regular 100Hz update tick.

Wheel Speed

The wheel speed sensor measures the speed of a hall effect wheel speed sensor. The sensor driver assumes that the spacing of the teeth is uniform, and that the high/low size of the sensor teeth are equal. The number of teeth is configurable at init. The sensor will produce a new reading every 1 second.

The voltage input appears as a PWM signal. The frequency of the PWM signal encodes the wheel speed.

The module implements an ISR (that is invoked by the Global Interrupt Handler). This does a GPIO read on the wheel speed sensor hall effect inputs, and then pushes these values to an RTOS queue. In the main task, the driver pulls these readings off, and calculates the number of 0V -> 24V transitions over the 1s period, informing a simple conversion to RPM.

Power Distribution Module (PDM)

This module is simply an abstraction to access the correct GPIO pins to control the 24V power output channels. When updating a power channel, the module will also reflect the change in the Vehicle State module.

Shutdown Circuit (SDC)

The module serves two purposes:

• A simple abstraction to access the ECU error output
• Update the Vehicle State when any of the SDC error inputs (BMS error, IMD error, SDC error) is asserted.

The Global Interrupt Handler invokes the SDC ISR method when the GPIO interrupt is triggered. The SDC ISR method will read the state of all the SDC inputs via a simple GPIO read. If any errors are asserted, a FreeRTOS task notification is used to awake the SDC task, finally updating the field in the Vehicle State.

PC Interface

The PC interface implements the serial (RS232) interface to a debug/control computer.

The following functions can currently be performed over the interface:

• Sending ECU log messages
• Sending ECU state updates
• Debug terminal

The serial interface communication is performed via a Modbus protocol. This allows the debug PC to multiplex the different types of data and handle independent operations. It also allows easier expansion of the PC interface.

Frame Format

Words are transmitted MSB first.

The console is configured to 115200 bps.

Byte Description

Address Names

Messages Types

State Broadcast

• FieldID ID of field. IDs are located at firmware/src/vcu/device/pcinterface/fieldId.h.
• FieldSize size of Data (bytes).
• Data[3..0] latest contents of field.

Log Message

• LogChar ASCII byte

Debug Console Message (PC to ECU)

• CmdStr String to append to the internal command buffer.

Debug Console Message (ECU -> PC)

This message ID is currently TBD. The current implementation prints log messages when handling debug console requests.

Multi-purpose IO (MPIO)

Implements a simple wrapper around the multi-purpose IO components on the ECU board. Allows an ADC read operation, or simple GPIO read/write.

The module will set the output mode pin. As with the ADC/GPIO drivers, the STM32-specific pin configuration is done seperately.

IMU

The board contains a MPU-6050 IMU. The IMU interfaces over the I2C bus.

The data from the IMU (accelerometer and gyroscope) would be pushed into the vehicle state.

This data is currently not used for any vehicle control and exists for offboard analysis.

This module is currently unimplemented.

Dashboard output

The current dashboard consists of a single LED output and button input. The dashboard output controls a single GPIO pin.

Peripheral Driver/Lib Layer

CAN

The CAN bus module provides a thread safe wrapper around the CAN bus hardware on the STM32. The CAN interface is accessed via the STM32 HAL internally.

FreeRTOS queues and semaphores are used to gate access to the peripheral, with access to three in parallel possible. The internal queues allow any FreeRTOS thread/task to enqueue a CAN tx message by making CAN_SendMessage thread safe. The module does this by using CAN_SendMessage to place pending messages on a queue and automatically sending queued messages when Tx complete interrupts trigger.

This module also implements the CAN rx ISRs. Other code modules can register to "listen" for CAN messages. The other code modules register a queue where their CAN messages can be placed and a FreeRTOS notification structure to notify. When the rx ISR is triggered, the CAN message is read, the appropriate target queues are found via the registered CAN IDs, the message is copied to the appropriate queues, and the appropriate task notifications are made.

I2C

The I2C driver provides a thread safe wrapper of the STM32 HAL DMA I2C interface. The driver will wait for the hardware to become free (up to a timeout).

One difference to the CAN bus driver is that it works synchronously with Read and Write operations, and does not allow for registering for responses (the I2C comms are completed inline).

SPI

The SPI driver works similarly to the I2C driver in that it provides a thread safe wrapper around the SPI peripherals. However, a simple SPI transfer (and a blocking transfer) are provided.

The blocking transfer uses the STM32 HAL blocking API and will busy loop while waiting for the transfer to complete.

The non blocking transfer uses DMA to perform the transfer and immediately returns when the transfer has begun.

UART

The UART driver works almost entirely the same as the CAN driver:

• The UART_SendMessage will either send the message directly to the UART hardware, or place it in a software queue if the hardware is already performing a transfer.
• For receive, the API allows for setting a receive data stream. The receive interrupt (which can handle variable length data using the frame end detection) will place data on the stream as it receives data. Unlike CAN, only one consumer can be applied per UART interface.

The STM32 hardware allows the U(S)ART to be managed via DMA, so this driver utilizes the DMA controller to run the UART interfaces.

ADC

The ADC driver configures the ADC peripherals to read via DMA and provide a thread safe interface (a simple ADC_Get once the device is running).

A helper function to apply linear scaling is also provided.

GPIO

This module of code simply adds an abstraction layer above the STM32 HAL GPIO code to improve code portability. This layer is intended to fully cover the peripheral capabilities, so a simple GPIO wrapper is needed.

RTC

Similarly to the GPIO, this module wraps around the STM32 HAL RTC driver.

Task Timer

The task timer module implements the timer ISR and sends FreeRTOS task notifications. Tasks can notify for period notifications (e.g. tasks that run at 100Hz) that allow them to run exactly at a specific frequency.

The depdendent tasks can pend on a notification until the task timer notifies them that they can run. This allows 100Hz tasks to run exactly at 10ms intervals without delay (regardless of run-time jitter).

The hardware is configured with an external crystal, making the timing highly accurate. The timer has been tested to maintain timing accuracy up to 20kHz.

When timing is above 1kHz, FreeRTOS scheduling must be recalculated. This currently isn't in place as the ECU only requires 100Hz.

CRC

This module is a simple wrapper around the STM32 CRC calculation hardware.

Logging

The logging module's use is to provide the Log_Print method which replaces printf.

The logging module will opertionally output the log data to two sources:

• SWD SWO - the SWD header is wired to support the SWO pin, so when using a debugger, SWO signals can be monitored, and the logging module can copy all log data to this interface.
• An arbitrary stream - this can be configured to copy data to any software stream. In practice, the PC Interface module will invoke Log_SetSerialStream to consume the log data, and will subsequently encode the logs onto a special serial structure for a connected PC on the UART interface.

Depends

Each module can use the REGISTER* macros to get a module ID which can be depended on by other module. Modules' init methods can invoke a DEPEND_ON or DEPEND_ON_STATIC method to ensure that other code that a particular module depends on has actually been initialized.

STM32 HAL

The STM32 HAL is simply the ST Micro provided HAL for the STM32 F7 microcontroller.