Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/media/IPG_carmaker/IPG_Carmaker.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/IPG_carmaker/PEAK_to_PEAK.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 37 additions & 1 deletion docs/resources/ipg_carmaker.md
Original file line number Diff line number Diff line change
@@ -1 +1,37 @@
Coming Soon....
## Requirements

In order to use IPG Carmaker you need to obtain a licence:

- If doing simulation with our main ROS2 stack: **IPG Carmaker for Linux**
- If using HiL: **IPG Carmaker for Windows**

A limited number of these are provided to Formula Student teams free of charge.

## Motivation:

### Static presentations:

Historically our simulation presentation has been one of our weaker static events. Fully integrating IPG carmaker would inevitably put us in the top 10 for simulation.
### Better than our current solution:

As of writing this were currently still using EUFS sim, which does work, **but its not ideal**. We only test downstream with EUFS sim currently (i.e. state estimation, path planning, control) as **EUFS sim doesn't provide simulated camera or LIDAR data.**

**IPG carmaker does!**

Integrating IPG carmaker properly would mean **we can do full stack testing,** something we haven't done to date!
Comment on lines +17 to +21

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the grammar and product-name consistency.

Use “At the time of writing, we were still using EUFS Sim, which works, but it isn’t ideal” and “full-stack testing.” Keep the IPG CarMaker capitalization consistent throughout the page.

Proposed wording
-As of writing this were currently still using EUFS sim, which does work, **but its not ideal**.
+At the time of writing, we were still using EUFS Sim, which works, **but it isn't ideal**.
...
-Integrating IPG carmaker properly would mean **we can do full stack testing,**
+Integrating IPG CarMaker properly would mean **we could do full-stack testing,**

These edits address the supplied LanguageTool finding and adjacent grammar errors.

🧰 Tools
🪛 LanguageTool

[grammar] ~21-~21: Use a hyphen to join words.
Context: ...ker properly would mean we can do full stack testing, something we haven't do...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/resources/ipg_carmaker.md` around lines 17 - 21, Correct the grammar in
the referenced documentation text: use “At the time of writing, we were still
using EUFS Sim, which works, but it isn’t ideal,” change “full stack testing” to
“full-stack testing,” and consistently capitalize the product name as “IPG
CarMaker” throughout the page.

Source: Linters/SAST tools


### HiL testing

The HiL (Hardware in Loop) simulator for FS-AI is still under development by Ian Murphy at the time of writing. It has been used at competition as part of static inspection for teams who are struggling to interface with the car (which included us for quite a while!). We got away without having to interact with HiL at all this year but it can still serve as a valuable tool in order to test how you interface with the ADS-DV car and whether or not you are sending the right signals to the car.

As part of developing the PEAK-CAN interface for the car last year, a "PEAK-to-PEAK" wire was also constructed. It allows for the connection of two computers over CANbus.

![PEAK-to-PEAK connector](../media/IPG_carmaker/PEAK_to_PEAK.jpg)

## Overall structure for a FT-IPG simulator:

**This diagram is incomplete.** There is strong likelihood you will need proxy nodes to handle some of the inputs/outputs to IPG carmaker e.g. PointCloud to PointCloud2 converter (since our current stack only accepts LIDAR data with the ROS2 msg type PointCloud2)

![IPG simulator overview](../media/IPG_carmaker/IPG_Carmaker.jpg)

People working in simulation will likely be focusing on the green and orange portions exclusively.
67 changes: 67 additions & 0 deletions docs/tutorials/ASR.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# The ASR (Autonomous Systems Responsible)

## Key Terms:

| Term | Definition |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| **RES** | Remote Emergency Stop. The emergency stop device operated by the ASR. |
| **Dynamic Operation** | Use of the ADS-DV within an approved Dynamic Operating Area under the defined ASR and area-control rules. |


## Brief:

According to the IMechE Documentation, the role of ASR is defined as follows:

**"The responsible operator who supervises the ADS-DV and operates the RES."**

I'm going to designate numbers for these rules, not because they are provided, but because they might make them easier to remember.

#### Rule 1:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Keep the heading hierarchy valid.

Rule 1 jumps from ## Brief to ####; use ### and keep Rules 1–4 at the same level.

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 19-19: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4

(MD001, heading-increment)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/ASR.md` at line 19, Update the Rule 1 heading in ASR.md from
level four to level three, and ensure the headings for Rules 1–4 use the same
### hierarchy beneath ## Brief.

Source: Linters/SAST tools


There must always be a qualified Autonomous Systems Responsible person (ASR) present to operate the ADS-DV with the Remote Emergency Stop (RES).

*"Bottom line, you can't go using the ADS-DV car without the ASR present, and with the RES properly attached"*

#### Rule 2:

The ASR must keep the RES strapped securely around their waist and on their person at all times while the ADS-DV is active. It must not be held in one hand, put down, or moved out of immediate reach.

*"Keep the thing attached and held on you in a reasonable fashion. If you can't immediately press the E-Stop button in less than half a second, your probably wearing it wrong"*

### If there is anyting you get from this document, remember this:
Comment on lines +29 to +31

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the visible typos before publishing.

Use you're, anything, and You're in these operator-facing instructions.

Also applies to: 67-67

🧰 Tools
🪛 LanguageTool

[style] ~29-~29: Consider replacing this phrase with the adverb “reasonably” to avoid wordiness.
Context: ...Keep the thing attached and held on you in a reasonable fashion. If you can't immediately press the E-S...

(IN_A_X_MANNER)


[grammar] ~31-~31: Ensure spelling is correct
Context: ...bly wearing it wrong"* ### If there is anyting you get from this document, remember th...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/ASR.md` around lines 29 - 31, Correct the visible typos in the
operator-facing text: change “your probably” to “you're probably,” “anyting” to
“anything,” and capitalize “you’re” as “You're” in the reminder heading. Apply
the same correction to the additional occurrence noted by the review.

Source: Linters/SAST tools


#### Rule 3:

### **"The ASR must only be responsible for mission selection and the RES. They must not perform any other duties while the ADS-DV is active."**

Your primary role is isolated to these 2 things, the mission selection (also setting the mission) and the RES. Everything else about the role is about promoting and ensuring the safety of yourself and others. **You must not have any other interaction with the vehicle of any kind.**

The whole point of this is to let the ASR have their full attention on the RES at any given moment in time during both Static and Dynamic Operation.

#### Rule 4:

During static and dynamic operation, you the vehicle and operation of the RES switch must have your absolute undivided attention

*Your eyes should be plastered to the vehicle at all times during static and dynamic operation*
Comment on lines +41 to +45

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Clarify the operator-attention rule.

The sentence at Line 43 is not grammatically parseable, and the informal wording at Line 45 leaves the required behavior unclear. Rewrite it as a direct instruction describing exactly where the ASR’s attention must remain.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/ASR.md` around lines 41 - 45, Rewrite Rule 4 in
docs/tutorials/ASR.md as a clear, grammatical direct instruction requiring the
ASR’s undivided attention to remain on the vehicle and operation of the RES
switch during both static and dynamic operation. Replace the informal “eyes
should be plastered” wording with precise language describing where attention
must remain.


## What to do if...

### The light on the status light on the emergency stop button starts flashing:

The RES battery is running low. Ask an IMechE official for support. (Rules also state how to change the battery)

### The RES starts vibrating randomly:

*"Your phones in your pocket mate" - ZF guy*
Comment on lines +49 to +55

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Repo files matching ASR docs:"
fd -a 'ASR\.md$|asr|ASR' . | sed 's#^\./##' | head -50

echo
echo "Section around docs/tutorials/ASR.md lines 1-90:"
if [ -f docs/tutorials/ASR.md ]; then
  cat -n docs/tutorials/ASR.md | sed -n '1,110p'
fi

echo
echo "Search for RES fault/emergency stop instructions:"
rg -n -i "RES|emergency stop|emergency.*stop|vibrat|flashing|ask.*official|stop|isolate|resume|operation" . --glob '!node_modules' --glob '!dist' --glob '!build' | head -200

Repository: FT-Autonomous/ft_docs_2.0

Length of output: 42926


Make RES fault handling fail-safe.

Both RES fault replies describe symptoms instead of safety-critical actions: a flashing status light, low battery, and unexpected vibration should specify whether ADS-DV operation must be stopped/isolated, the exact battery or RES inspection/replacement steps, and clearance before the next run.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/ASR.md` around lines 49 - 55, The RES fault-handling guidance
in the “light on the status light” and “RES starts vibrating randomly” sections
must specify fail-safe actions: stop and isolate ADS-DV operation, identify the
required battery or RES inspection/replacement procedure, and state the
clearance required before the next run. Replace the symptom-only text with these
actionable steps, using the established emergency-stop and RES procedures where
available.


### Anything about the Static or Dynamic operation of the ADS-DV during present or future operation is unsafe:

EBS and stop interacting with the vehicle in a safe manner and assess the situation.

Comment on lines +57 to +60

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Files:"
git ls-files | rg '\bASR\.md$|docs/tutorials/ASR\.md' || true

echo
echo "Target section with line numbers:"
if [ -f docs/tutorials/ASR.md ]; then
  sed -n '1,120p' docs/tutorials/ASR.md | nl -ba
fi

echo
echo "Search for EBS/RES in ASR doc and repo:"
rg -n '\b(EBS|RES|RES_S|RES_)|emergency|stop|interacting with the vehicle' docs/tutorials/ASR.md . --glob '!**/.git/**' --glob '!node_modules/**' | head -200

Repository: FT-Autonomous/ft_docs_2.0

Length of output: 268


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Target section with line numbers:"
sed -n '1,120p' docs/tutorials/ASR.md | awk '{printf "%6d  %s\n", NR, $0}'

echo
echo "Search for EBS/RES in ASR doc and repo:"
rg -n '\b(EBS|RES|RES_S|RES_)|emergency|stop|interacting with the vehicle' docs/tutorials/ASR.md . --glob '!**/.git/**' --glob '!node_modules/**' | head -300

Repository: FT-Autonomous/ft_docs_2.0

Length of output: 16971


Reconcile the EBS/RES controls.

In the ASR doc, RES is the only ASR-operated emergency-stop device that is defined, so replace the undefined/emergency-ambiguous EBS/EBS switch wording at lines 59 and 65, or add EBS as an Emergency Brake System control and clarify the ASR’s exact action for each. Line 59 also needs a complete imperative, e.g. Hit the RES and stop....

🧰 Tools
🪛 LanguageTool

[style] ~59-~59: Consider replacing this phrase with the adverb “safely” to avoid wordiness.
Context: ...S and stop interacting with the vehicle in a safe manner and assess the situation. #### *Case s...

(IN_A_X_MANNER)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/ASR.md` around lines 57 - 60, The ASR emergency-stop guidance
uses undefined or ambiguous EBS terminology and an incomplete instruction.
Update the affected guidance in the ASR document to use the defined RES control
consistently, with a complete imperative instructing the operator to activate
RES and stop safely; alternatively, define EBS as a control and explicitly
distinguish the ASR action for EBS versus RES.

#### *Case study*

During the Sunday of FSUK 2026, people around me, the ASR were busy putting cones out in a rush in order to get a run in the newly designated practice area with the ADS-DV. The proposed run involved increasing the speed of the ADS-DV since the last run dramatically.

As the ASR I noticed that the cones that were laying out the proposed track were a little bit close to the tyre barrier for my liking at one corner. The officials around the vehicle did not have any complaints, but as the ASR (and knowing the fact that we were increasing our speed on that run), I would have felt much more comfortable had the track been a metre or two further out from the tyre barrier. The ADS-DV vehicle in this case overshot the first turn due to the high speed it was carrying in the first corner, but had it have been carrying the same speed in the corner closer to the tyre barrier, it could have posed a potential hazard, even though I hit the emergency stop well before it reached that corner. **In this particular case, all operation should have been halted until the track layout met my standard.** As the ASR, you have to look out for yourself, and the others around you. The EBS switch can't be treated as though it will cause the car to come to an immediate stop. **You must account for a reasonable amount of runoff (4 metres minimum)**.

It might seem annoying, but you have to have an element of cop on when it comes to these things. **Your the person who should be enforcing safe operation of the vehicle.**
14 changes: 14 additions & 0 deletions docs/tutorials/onboarding_videos.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Onboarding videos

This page includes some basic videos showcasing where to find the certain POIs (Points Of Interest) regarding Formula Trinity Autonomous

### Finding the FT-Autonomous Locker and the "Rigby-Room":
Comment on lines +3 to +5

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the page copy and heading level.

The opening sentence is awkward, and ### skips directly from the page title. Use ## and concise wording such as “This page includes basic videos showing where to find key points of interest (POIs) for Formula Trinity Autonomous.”

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 5-5: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/onboarding_videos.md` around lines 3 - 5, Update the opening
sentence to concise wording describing basic videos for finding key points of
interest (POIs) for Formula Trinity Autonomous, and change the “Finding the
FT-Autonomous Locker and the "Rigby-Room":” heading from level three to level
two.

Source: Linters/SAST tools


<div class="video">
<iframe
src="https://youtube.com/embed/kwHWlXzgEdo"
title="FT-Autonomous Locker and the 'Rigby-Room'"
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen></iframe>
</div>
4 changes: 2 additions & 2 deletions docs/tutorials/python_to_cpp.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
### Note:

Its important to note that this is only a guide to migrate from Python to C++, not necessarily a mandatory read.
Many people prefer to work with Python for its dynamic types, but besides user readability C++ is the most optimal language for robotics as C++ is much closer to assembly language, both in terms of structure and performance.
Many people prefer to work with Python for its dynamic types, but besides user readability, C++ is the most optimal language for robotics as C++ is much closer to assembly language, both in terms of structure and performance.

## Reasons for wanting to migrate:

- C++ code runs miles faster than Python
- No dynamic types ( you know excatly what every variable should be storing )
- No dynamic types ( you know exactly what every variable should be storing )

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use clearer wording for the dynamic-types bullet.

Remove the spaces inside the parentheses and prefer “what each variable stores”:

Proposed wording
-- No dynamic types ( you know exactly what every variable should be storing )
+- No dynamic types (you know exactly what each variable stores)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- No dynamic types ( you know exactly what every variable should be storing )
- No dynamic types (you know exactly what each variable stores)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutorials/python_to_cpp.md` at line 9, Update the dynamic-types bullet
in the Python-to-C++ tutorial to remove the spaces inside the parentheses and
use the clearer wording “what each variable stores.”

- A very good way to understand how your code is actually working, and whether or not there are any mistakes in your current code.
- Avoiding bottle necks in performance for small but necessary ROS2 nodes and packages

Expand Down
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,7 @@ nav: # This is the structure of the sidebar

- Tutorials:
- Getting Started Guide: tutorials/Getting_started.md
- Onboarding Videos: tutorials/onboarding_videos.md
- Cutting Bags Down to Size: tutorials/cutting_bags.md
- Competition Launch Scripts; Configuration, Setup and Running them: tutorials/comp_launch_scripts.md
- Reducing Boot Time: tutorials/reducing_boot_time.md
Expand All @@ -162,6 +163,7 @@ nav: # This is the structure of the sidebar
- LiDAR Setup: tutorials/lidar_setup.md
- YOLO Training: tutorials/yolo_training.md
- Webpage Setup: tutorials/webpage_setup.md
- The role of the ASR: tutorials/ASR.md

- Equipment:
- ADS-DV Vehicle: equipment/ads_dv.md
Expand Down
Loading