sfuphantom / vcu-fw

Vehicle Control Unit - Firmware for the TMS570LS1227 written upon the freeRTOS v9 platform

VCU-FW

Vehicle Control Unit - Firmware for the TMS570LS1227 written upon the freeRTOS v9 platform

Releases

Releases are read-only branches that express major milestones in development. They have been through some form of testing and are known to be stable. If you are not developing for the VCU, please use one of these branches.

Release	Information	Date
PhantomRelease1	Pull request	2023-03-02

Debug Commands

To interact with the VCU through a serial terminal (460800 baud rate), use the following numbers on the keypad.

ECHO_THROTTLE='1',
ECHO_APPS1='2',
ECHO_APPS2='3',
ECHO_BSE='4',
STAT_RUN='5',  // vTaskGetRunTimeStats
STAT_START='6',  // xTaskGetTickCount
TASK_LIST='7', // vTaskList
RESET_CAR='r',
START_ENGINE='s',
TURN_TRACTIVE_ON='o',

(1,2,3,4) Echo the value of Throttle, APPS1/APPS2, and BSE respectfully

33%

(6) View live scheduler tick count

1029894

(7) View run time statistics for each task

Task          State   Prio    Stack    Num
********************************************
VCU_CLI         R       0       314     1
IDLE            R       0       226     3
ThrottleTask    B       4       84      2
Tmr Svc         B       1       474     4

vcu-fw's Issues

Implement capture logs

For better debugging of sensor input/output signals, implement the following:

https://electricfiredesign.com/2023/01/31/debugging-with-capture-logs/

4D: VCU Simulation Mode

This is the firmware side of VCU-4A. Essentially, write a single C function that does the parsing on the firmware side here.

Make sure it compiles and then we can test it in the lab in burnaby!

Checklist:

• Iron out design of encoding
• Implement in Python and C
• Test that it works with arbitrary data

Integrate with Kevin's scripts #32 once merged!

Create VCU Simulation Framework for Integration Testing

Issue Summary:
Develop a comprehensive VCU Simulation Framework that empowers users to conduct detailed testing of the vehicle's firmware under race-like scenarios. This framework will facilitate thorough verification of the VCU's behavior in response to various critical inputs and stimuli, including
-APPS (Accelerator Pedal Position Sensor)
-BSE (Brake System Enable) pedals
-RTD (Ready-To-Drive) signals
-Set-Reset-Flip Events
-TSAL (Transmission Shift Actuator Lock).

Scope and Purpose:
The primary goal of this framework is to enable rigorous integration testing of the VCU's behavior. It will provide a controlled environment where the VCU's responses to various inputs can be tested comprehensively. The testing scenarios will simulate real-world conditions, ensuring that the VCU functions correctly under different operational states.

Key Features:

• Realistic Race-Like Scenarios: The framework will allow users to mimic race-like conditions, creating a dynamic testing environment that closely resembles actual vehicle operation.

• Multi-Input Simulation: Users can simulate various critical inputs, such as accelerator and brake pedal actions, RTD signals, and shift actuator behaviors, to assess how the VCU responds.

• Detailed Event and State Testing: The framework will offer in-depth testing of VCU events and states, ensuring that the VCU behaves as expected in every operational phase.

Benefits:

• Thorough Verification: Integration testing with this framework will enable comprehensive verification of the VCU's functionality and ensure that it responds correctly to a wide range of inputs and stimuli.

• Early Issue Detection: The ability to simulate real-world scenarios will allow for early detection of potential issues and improve the reliability of the VCU.

• Robust Validation: The framework will validate the correctness of the VCU's events and states, enhancing the overall safety and performance of the vehicle.

Additional Information:
This issue seeks to create a flexible and effective VCU Simulation Framework that enhances integration testing. Your contributions and ideas are highly valued to ensure the successful implementation of this framework. Please provide your insights and suggestions on how to best achieve this objective.

Queue

Establish queue to send VCU data back and forth between tasks and interrupts.

Schedule CAN transmissions

The CAN/Networking team should be responsible for creating the API that can send all messages defined for the car.

This issue is concerned with prioritizing and scheduling the transmission of VCU messages by calling the CAN API within the our codebase

Clean up stale branches

Steps:

1. Figure out which branches are stale aka not being used anymore (ex. no branch activity for > 6 months)
2. Delete the stale branches

3C: Reorganize and integrate into current setup

Blocked by 3B for now

IMD Driver Implementation

Implement the IMD driver into the VCU codebase to properly interpret messages.

The driver is in but it's currently not reading any valid data. The data is being simulated by a PWM signal from the same microcontroller. When run in its own program outside of the VCU codebase it works fine. When running within the VCU codebase the HET interrupts don't appear to be firing

Update throttle encoding scheme

Update the throttle encoding scheme to include BSE and RTDS values. This should enable us to simulate all inputs going to the VCU and more easily test software logic.

https://docs.google.com/document/d/1JWH6s5qf8QeWGzkVzae5GWXK8BNsT8EGFw0WuFVnmiY/edit

vcu-fw/VCU/Phantom/tasks/source/task_throttle_agent.c

Line 94 in 5a94530

// TODO: Add the rest of the direct VCU inputs to the encoding scheme

Display results of TASK_LIST command through delayed interrupt handling

Currently, displaying the entire task list inside the IRQ puts the MCU into an abort state because there are wayyy too many characters to process and send over UART. We need a simple implementation (IRQ flag and volatile static array) to process the data whenever the VCU has time.

Maybe this could happen in the interrupt task?

vcu-fw/VCU/Phantom/Drivers/UART/Phantom_sci.c

Line 125 in a6cba00

// TODO: use interrupt task (this aborts because it's too many chars to send in an IRQ)

Write ISR for BOTS

3A: Cleanup VCU data structure

Remove everything in the data structure and figure out how that logic and state will be supplemented

1A: Create hardware testbench and run through oscilloscope

We need a reliable way to test our system and get the gist of the characteristics of the throttle system. This will also be useful for testing other parts of the VCU by having a reliable way to get steady, sane values.

We will need to create a rough sketch or schematic drawings with resistor values to rebuild test bench if necessary and some captioned oscilliscope pictures

Data Structure

Create a data structure to hold all the data the VCU collects. Analog voltages, digital outputs, and keep track of internal states and outputs.

1B: Test with inverter simulation

Apparently, Power has a simulator that essentially measures some voltage and tells us what the throttle of the motor would look like. This would be one level of testing above VCU-1A so ideally, we should test with the custom test bench first, but we can also start with this test and finetune and test with the custom test bench later

Outputs:

• Test documentation and results/learnings

4B: Throttle software simulation

This will be built on the foundation of the command line tool in VCU-4A. It’s purpose is to help characterize the throttle response by allowing us to create arbitrary waveforms in software without the need for a signal generator.

Refactor a little bit. Make it more object-oriented
Map real pedal value before: (apps, app2, bse) -> Mapped to a voltage
After: (footpedal angle) -> maps to throttle output

Checklist

• Apps1
• Apps2
• BSE

Handle SET/RESET logic

APPS Implausibility

According to rule from 2022 Formula SAE official rules,
T.4.2.5 If an implausibility occurs between the values of the APPSs and persists for more than 100msec, the power to the (IC) electronic throttle / (EV) Motor(s) must be immediately stopped completely.
(EV only) It is not necessary to Open the Shutdown Circuit, the motor controller(s) stopping the power to the Motor(s) is sufficient.

Objective
Change the necessary code in the throttle task such that when an APPS implausibility (APPS1 & APPS2 differs by more than 10%) occurs, we ignore all consequent throttle commands, or set THROTTLE_AVAILABLE to false. Double-check this solution with the controls team.

Configure interrupt to detect RTD Switch

Configure the hardware interrupt to trigger from the RTD switch and notify the state machine accordingly

Read FSAE rules and identify unit tests for VCU

Sections to read include:

• T.3.2 - Brake Over Travel Switch (BOTS)
• T.4.2 - Accelerator Pedal Position Sensor (APPS)
• T.4.3 - Brake System Encoder (BSE)
• EV.5.7 - APPS / Brake Pedal Plausibility Check
• EV.6.9 - Tractive System Active Light (TSAL)
• EV.8.1 - Shutdown Circuit
• EV.8.2 - Shutdown Circuit Operation
• EV.10.4 - Activation Sequence
• EV.10.5 - Ready to Drive Sound

Add SET/RESET signal to VCU simulation

4C: Software State Machine Tests

This will be built on the foundation of the command line tool in VCU-4A. Its purpose is to validate the state machine task. It is only concerned with the logic (we don’t necessarily care too much about race conditions in the scope of this task). These would essentially be small “unit tests”.

This would help with the vast number of inputs to the state machine and establish some basic but integral regression tests.

Outputs:
Full design doc explaining all design decisions (we want to be very explicit about the capabilities and drawbacks of this simulation)
Be able to do something like ./run_state_tests and either fail or generate a report

Handle CAN messages

When CAN messages are received either through interrupts or polling (to be decided by the CAN/Networking team), the firmware will need to dispatch and redirect the messages to the appropriate thread to handle and/or store the information.

Research new APPS and BSE

We need more accurate sensors that also work with Dynamics' mounting plan so this is to see what kind of sensors are on the market to replace the old ones.

LV Driver Readings

Getting voltage and current readings separately from the INA226 using David's LV monitor I2C driver. Then storing these in to the VCU data structure and integrating fault checks on the measurements.

The min/max values need to be defined for low voltage current+voltage and should be included in the vcu_rev2.h and launchpad.h files.

Write ISR for SET/RESET

#50 (comment)

EEPROM Driver

• Create an EEPROM driver to be able to save the VCU state periodically to flash. In the case of a power cycle or reset event, the VCU should be able to read the flash upon bootup and decide if it should load in the old vehicle state or not.

• Ensure the driver works for both launchpad and VCU.

• Documentation for how the driver works, and how the implementation/application works.

Current Sensor Readings

Implement analog readings for current sensor. This sensor measures the high current path between battery and inverter. This will be able to measure both positive and negative currents. Negative will correspond to regenerative braking.

• Include max positive current level and min negative current level as defines in the board_hardware.h file for both launchpad and VCU.

• Write out a function that can convert the current sensor 0->5V analog signal into a current. You will need to use the current sensor datasheet to get the proper mapping function.

• Write out some error checking and a function that throws a fault if the current reading is not in the proper bounds.

• Package the functions into a driver (current_transducer.h/current_transducer.c) and put it in its own folder similar to where the DAC_SPI driver folder is

• Implement the function calls from the driver in the VCU's sensor_read task

3B: Explicitely define type of FSM and unit test

This is going to be a big (hopefully simplistic) redesign of the state machine. There are two parts here the state machine itself and the freeRTOS task. For the former, I want a more formal and explicit state diagram that dives into its type (Mealy or Moore) and has a proper state machine diagram.

For the latter, the emphasis is on decentralizing fault checks. To see what I mean, look at this. This task has none of its logic abstracted away by drivers. It just adds a layer of state variables that need to be constantly synched with hardware to determine its state. The events that define a certain state switch are centralized in this file. This makes it hard to see the structure of the state machine itself. This was designed from a very bottom-up approach. It is incredibly hard to tell what the inputs are and how to test them.

Instead, I think we should have a very explicitly defined set of states that get passed in as an enum to determine the state of the machine. If all fault scenarios lead to the same meaning ie APPS or BSE range fault -> SENSOR_RANGE_FAULT, then this would simplify the logic a lot. To add more fault scenarios would mean doing a check anywhere in the program and then posting a SENSOR_RANGE_FAULT event for the state machine to process.

Now from the freeRTOS side, this means that the state machine should act as a software interrupt where it immediately handles any event that is given to it. This can be done by giving it the highest priority of the tasks and ensuring its work boils down to a series of if statements (so as not to starve the processor). It can wait on an event queue to do actual work.

The outputs or consequences of the state should also be present in this task instead of spread out across the program.

Modify TSAL logic for new Power PCB design

Driver Controls

Goal: Improve and add to the throttle task to ensure we are processing all foot pedal data properly.

Things to be added:

• BSE valid range check
• APPS 1 and APPS 2 valid range check
• Brake Plausibility Check
• 10% APPS difference check
• Driver_Controls driver that packages all checks into nice functions (i.e. getPedalReadings(), check10Percent...)
• Everything stored in the VCU data structure

Pathway to Completion

1. Pseudocode with all desired changes
2. Pseudocode review
3. Add all required #defines to board_hardware.h file
4. Create the driver_controls driver
5. Begin to write each function and add to the throttle task (test in between each addition)

Implement Unit Tests for VCU Firmware

Issue Summary:
This issue aims to add unit tests to the VCU firmware to ensure its compliance with the FSAE (Formula Society of Automotive Engineers) rulebook. Unit tests play a crucial role in validating the functionality and robustness of the VCU software.

Scope and Purpose:
The primary objective is to develop a comprehensive set of unit tests based on the requirements gathered from the FSAE rulebook. These tests will evaluate the VCU firmware's functionality, performance, and compliance with the specified standards. Unit testing is a critical step in identifying and rectifying potential issues in the software.

Key Tasks:

1. Requirement Gathering: Gather all relevant requirements and specifications from the FSAE rulebook that pertain to the VCU firmware.

2. Test Plan: Create a test plan that outlines the scope, objectives, and test cases to be implemented.

3. Test Implementation: Develop unit tests in a specific test folder using the Python pytest module. These tests will assess various aspects of the VCU firmware, ensuring it adheres to the defined rules and regulations.

4. Documentation: Document the test cases, test results, and any deviations from the rulebook requirements.

5. Integration: Integrate the unit tests into the VCU firmware's development process to enable automated testing.

Unit Tests Significance:
Unit tests are a vital component of the firmware development cycle. They play a pivotal role in maintaining the software's integrity and reliability. Any changes made to the firmware can be quickly validated by running all unit tests, ensuring that new developments do not introduce defects and that the software remains compliant with the FSAE rulebook.

Reference:
For detailed information on the unit tests and their specific requirements, please refer to Issue #59.

Benefits:

• Quality Assurance: Unit tests will enhance the quality and reliability of the VCU firmware, ensuring it meets the standards set by the FSAE.

• Issue Identification: Unit testing will help identify and resolve potential issues at an early stage, reducing the likelihood of defects in the final product.

• Compliance: By adhering to the FSAE rulebook through rigorous unit testing, the VCU firmware will demonstrate compliance with industry standards.

Output relevant signals during a severe fault scenario

I'm being vague because there may be other things to consider, but I think we have to notify the SDC in this event

Clean up repo

Can we can delete these?

Can we include some of these into the .gitignore?

Why are there two .gitignores?

Create a simple unit test for one fault event

Read through the VCU Design document for more context before starting this task

Fix Throttle Fault Timers

We need to figure out when these are triggered so that we can avoid them when developing and testing other features. It's also possible that these don't really work as expected...

vcu-fw/VCU/Phantom/tasks/source/task_throttle_actor.c

Line 110 in a6cba00

// TODO: Add range fault checks

Move to tractive off state when high voltage is off

https://viewer.diagrams.net/?page-id=BhlIVNj5Ru_8s9wX0_BA&highlight=0000ff&edit=_blank&layers=1&nav=1&hide-pages=1#G1uKblakAovlpPvJciPE8IRBLEZo3NYH4g

The BMS will be sending a TSAL bit over CAN to the VCU. The job of sending that information is left to the CAN team.

Create a new event in eCarEvents and implement the necessary logic in the VCU state machine according to the diagram linked above.

You may add to the command list to inject the event for testing

Implement BOTS logic

Gather characteristics of the BOTS signal ie active high/low, logic level, etc
Add new event to eCarEvents and notify state machine
Test using CLI

Design and implement variable polling commands

Figure out a neat way of implementing the commands to poll sensor values from the system. You should confirm the design before touching the code

2B: Handle the RTD procedure

This function will handle the ready to drive (RTD) procedure as per the rule book requirements. When the driver flips a switch the function will check if the brake is pressed and if the tractive system is active. If both the brake is pressed and the tractive system is active the function will enable the motors to respond to inputs from the throttle.
The brake being pressed is determined by checking if the sensor value is above a specific threshold. If the tractive system is active is determined by checking the status of the TSAL function (previously written function).

4A: Command Line Interface for passing throttle values

Before testing real throttle petal values (APPS1, APPS2, BSE), we must ensure that the VCU code accurately processes input values. This script will be a Python command line interface for passing values from your local CMD/Terminal to the microcontroller:

This interface is tailored towards the refactor in this branch:

https://github.com/sfuphantom/vcu-fw/blob/Throttle-refactor/VCU/Phantom/Drivers/THROTTLE/README.md