Repository navigation
Adds interface system overview #25
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Autonomous System Break | ||
|
|
||
| The ASB serves to allow the autonomous system to slow itself down, however the supervisor for this system is very mission critical and such it also has the option to trigger the ShutDown Circuit and in turn the Emergency System Break. The supervisor should monitor the other electronic systems to ensure they do not stall (if they do: SDC), and is itself monitored by a hardware watchdog that requires a heartbeat or else it will trigger the SDC. | ||
|
|
||
| ## What signals does it monitor and what does it care about them | ||
|
|
||
| It monitors the CANbus to ensure that no system has stalled. Every system should update the values associated with it every X amount of time. If they fail to do so, the supervisor should trigger the SDC. 100ms is a reasonable time for this if CANbus is at 50Hz (FSG Rules define 500ms as the longest digital signal timeout permissable). | ||
|
|
||
| - Pi/Jetson sends heartbeat through the PCAN link | ||
| - ESPs sensor data changing should constitute a heartbeat | ||
|
There was a problem hiding this comment. 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win Do not make sensor-value changes the heartbeat. A valid signal can remain constant, such as zero speed or fixed steering. If the payload must change to count as a heartbeat, the supervisor can falsely trigger the SDC. Require periodic heartbeat or status frames and monitor frame arrival or sequence independently of payload values. 🤖 Prompt for AI Agents |
||
| - Test to ensure it is able to detect a broken wire, a short to ground, an analogue sensor short to supply, an implausible or out-of-range sensor value, and corrupt, missing or delayed digital messages. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,74 @@ | ||
| # Systems Overview | ||
|
|
||
| This page details how the AI/ADS interface works. **Currently the system has not been built yet so the details on this page are subject to change, however we are attempting to build to this vision so they should not vary wildly. This notice will be removed once the system is built and relatively stable.** | ||
|
|
||
| ## What is the AI/ADS interface anyways? | ||
|
|
||
| Interface is the layer that stands between the control team on software and the integration team on hardware. This means that we will be getting in details as to what acceleration and steering angle to reach from Control's ROS node, using that to dictate how the various actuators and motors around the car operate, reading data back from a number of sensors we have, and adjusting based off of that. We also have to monitor the systems we create to ensure they do not fail, and if they do we engage the Shut Down Circuit (SDC) to shut the car down and engage the Emergency Braking System (EBS). | ||
|
|
||
| ## How do we achieve this | ||
|
|
||
| ```mermaid | ||
| graph LR | ||
| subgraph Ethernet | ||
| JT["Autonomous Software Stack Jetson"] | ||
| PI["Raspberry Pi/Jetson"] | ||
| NT["Nanotec N5"] | ||
| JT <--> PI | ||
| PI <--> NT | ||
| end | ||
| ZX["ZedX"] | ||
| XS["XSens"] | ||
| SM["Steering Motor"] | ||
| ZX --> JT | ||
| XS --> JT | ||
| NT --> SM | ||
| PI <-- USB --> PK | ||
| subgraph CAN bus | ||
| PK["PEAK PCAN-LINK"] | ||
| TE["Throttle ESP"] | ||
| SE["Steering ESP"] | ||
| CE["Clutch ESP"] | ||
| GE["Gear ESP"] | ||
| HE["HMI ESP"] | ||
| AHE["Auxillary Health ESP"] | ||
| DS["DEWEsoft Logger"] | ||
| ME["Microsquirt ECU"] | ||
| subgraph ASB Supervisor | ||
| AS["ASB Supervisor ESP"] | ||
| HW["Hardware Watchdog"] | ||
| AS -- Heartbeat --> HW | ||
| end | ||
| TE .-> AS | ||
| SE .-> AS | ||
| CE .-> AS | ||
| GE .-> AS | ||
| HE .-> AS | ||
| ME .-> AS | ||
| PK <--> TE | ||
| PK <--> SE | ||
| PK <--> CE | ||
| PK <--> GE | ||
| PK <--> HE | ||
| PK <--> AHE | ||
| PK <--> AS | ||
| ME --> PK | ||
| end | ||
| SDC["SDC Latch"] | ||
| AS --> SDC | ||
| HW --> SDC | ||
| ``` | ||
|
|
||
| ### ASB Supervisor | ||
| - Monitors Autonomous System Brake (ASB) and ESB, if checks fail, engages SDC. | ||
|
Comment on lines
+7
to
+63
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: rg -n -i 'autonomous system (break|brake)|emergency system (break|brake)|\bASB\b|\bEBS\b|\bESB\b|Break ESP|Brake ESP' docs mkdocs.ymlRepository: FT-Autonomous/ft_docs_2.0 Length of output: 5028 🤖 get_repo_knowledge executed:
Length of output: 1744 🏁 Script executed: #!/bin/bash
printf '%s\n' '--- FSG and terminology references ---'
rg -n -i 'FSG|formula student|autonomous system (break|brake)|emergency system (break|brake)|emergency braking system|break ESP|brake ESP|\bASB\b|\bESB\b|\bEBS\b|\bESP\b' . -g '!node_modules' -g '!build' -g '!dist' | head -n 240
printf '%s\n' '--- affected source context ---'
sed -n '25,72p' docs/ads/aiads_interface/overview.md
printf '%s\n' '--- ASB page ---'
cat -n docs/ads/aiads_interface/asb.md
printf '%s\n' '--- navigation context ---'
sed -n '125,145p' mkdocs.ymlRepository: FT-Autonomous/ft_docs_2.0 Length of output: 12557 🏁 Script executed: rg -n -i 'FSG|formula student|autonomous system (break|brake)|emergency system (break|brake)|emergency braking system|break ESP|brake ESP|\bASB\b|\bESB\b|\bEBS\b|\bESP\b' . -g '!node_modules' -g '!build' -g '!dist' | head -n 240
printf '%s\n' '--- affected source context ---'
sed -n '25,72p' docs/ads/aiads_interface/overview.md
printf '%s\n' '--- ASB page ---'
cat -n docs/ads/aiads_interface/asb.md
printf '%s\n' '--- navigation context ---'
sed -n '125,145p' mkdocs.ymlRepository: FT-Autonomous/ft_docs_2.0 Length of output: 12518 🌐 Web query:
💡 Result: <source_evidence> Citations:
Use the canonical ASB and EBS terminology. Use
Update the matching 🧰 Tools🪛 LanguageTool[style] ~7-~7: ‘off of’ might be wordy. Consider a shorter alternative. (EN_WORDINESS_PREMIUM_OFF_OF) 🤖 Prompt for AI Agents |
||
| - Monitors other ESPs and if they stall or behave irregularly, engages SDC. | ||
| - Watchdog needs to be on the same PCB. Watchdog recieves a heartbeat from the ASB Supervisor, if does not it engages the SDC. | ||
|
|
||
| ### Low Level Logic | ||
| - Each of the ESPs listed in the diagram needs to be programmed to deal with targets for its relevant domain and be able to adjust itself to achieve those (PID?) | ||
| - Each of the ESPs needs to be able to communicate over CAN bus a unified. This uses a 20AWG twisted pair as the wire, an Adafruit CAN Pal on each ESP32, the inbuilt TWAI controller driver using a prexisting [library](https://github.com/collin80/esp32_can). The twisted pair needs to be terminated with 120 omhs. | ||
|
There was a problem hiding this comment. 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win Document both CAN termination points. State which two physical bus ends receive 120 Ω termination. The current wording can be read as one resistor or as termination on every node. High-speed CAN uses one 120 Ω terminator at each bus end. (nxp.com) 🧰 Tools🪛 LanguageTool[style] ~72-~72: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing. (REP_NEED_TO_VB) [grammar] ~72-~72: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [style] ~72-~72: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing. (REP_NEED_TO_VB) [grammar] ~72-~72: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) 🤖 Prompt for AI AgentsSource: MCP tools 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Correct spelling and wording in the implementation guidance.
🧰 Tools🪛 LanguageTool[style] ~72-~72: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing. (REP_NEED_TO_VB) [grammar] ~72-~72: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [style] ~72-~72: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing. (REP_NEED_TO_VB) [grammar] ~72-~72: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) 📍 Affects 2 files
🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
|
|
||
| ### Raspberry Pi/Jetson | ||
| - Is a ROS node that forwards on the instructions gotten from control's node via CAN using the PCAN LINK. | ||
| - Returns details such as actual wheel angle, speed, etc, up the chain by publishing it. | ||
| - Using [ros2nix](https://github.com/wentasah/ros2nix) would be nice to minimise issues relating to setting up multiple redundant devices and migrating from one to another. This will also help to deal with compatability issues of ROS with different versions of Linux and reduce unessicary time spent compiling from source. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🏁 Script executed:
Repository: FT-Autonomous/ft_docs_2.0
Length of output: 2918
🤖 get_repo_knowledge executed:
get_repo_knowledge FT-Autonomous/ft_docs_2.0 /tmp/coderabbit-repo-knowledge/ft-autonomous-ft-docs-2-0-b2fa302a/architectureLength of output: 2871
🏁 Script executed:
Repository: FT-Autonomous/ft_docs_2.0
Length of output: 2764
🏁 Script executed:
sed -n '1,120p' docs/ads/aiads_interface/asb.mdRepository: FT-Autonomous/ft_docs_2.0
Length of output: 1352
Define the hardware-watchdog timing contract.
The document gives 100 ms as a reasonable CAN signal-monitoring interval, but it does not define the ASB heartbeat period or the hardware-watchdog deadline. Keep the FSG digital-signal timeout separate from the watchdog timeout. Add the startup grace period, missed-heartbeat action, and exact applicable FSG ruleset reference.
🤖 Prompt for AI Agents
Source: MCP tools