From 0822b04223baa8abe5b4faad98b9a4b402c1ab53 Mon Sep 17 00:00:00 2001 From: mbdalpha <166437418+mbdalpha@users.noreply.github.com> Date: Sun, 13 Sep 2026 19:28:41 +0100 Subject: [PATCH 1/6] Adds interface system overview --- docs/ads/aiads_interface/overview.md | 78 +++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/docs/ads/aiads_interface/overview.md b/docs/ads/aiads_interface/overview.md index eb04998..60d0444 100644 --- a/docs/ads/aiads_interface/overview.md +++ b/docs/ads/aiads_interface/overview.md @@ -1 +1,77 @@ -in development \ No newline at end of file +# 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["Jetson"] + PI["Raspberry Pi"] + 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"] + BE["Break 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 + BE .-> AS + HE .-> AS + ME .-> AS + PK <--> TE + PK <--> SE + PK <--> CE + PK <--> GE + PK <--> BE + 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. + - 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. + +### Raspberry Pi + - 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. \ No newline at end of file From 6354d3731e6a5b7a46c9c2ced5677e396893b5c3 Mon Sep 17 00:00:00 2001 From: mbdalpha <166437418+mbdalpha@users.noreply.github.com> Date: Mon, 21 Sep 2026 07:31:30 +0100 Subject: [PATCH 2/6] add small piece detailing the ASB --- docs/ads/aiads_interface/asb.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/ads/aiads_interface/asb.md diff --git a/docs/ads/aiads_interface/asb.md b/docs/ads/aiads_interface/asb.md new file mode 100644 index 0000000..e66e2de --- /dev/null +++ b/docs/ads/aiads_interface/asb.md @@ -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 +- 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. \ No newline at end of file From 3e474cfb46f18fa12cef295b12354bcde9fddef9 Mon Sep 17 00:00:00 2001 From: mbdalpha <166437418+mbdalpha@users.noreply.github.com> Date: Mon, 21 Sep 2026 07:32:53 +0100 Subject: [PATCH 3/6] detail use of Nix a bit more --- docs/ads/aiads_interface/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ads/aiads_interface/overview.md b/docs/ads/aiads_interface/overview.md index 60d0444..21d6ec0 100644 --- a/docs/ads/aiads_interface/overview.md +++ b/docs/ads/aiads_interface/overview.md @@ -74,4 +74,4 @@ graph LR ### Raspberry Pi - 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. \ No newline at end of file + - 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. \ No newline at end of file From ef7bed13390e860270df142eeb5cf9d7f7b04b36 Mon Sep 17 00:00:00 2001 From: mbdalpha <166437418+mbdalpha@users.noreply.github.com> Date: Mon, 21 Sep 2026 07:35:25 +0100 Subject: [PATCH 4/6] detail potential use of Jetsons instead of Pis --- docs/ads/aiads_interface/overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ads/aiads_interface/overview.md b/docs/ads/aiads_interface/overview.md index 21d6ec0..2697fe1 100644 --- a/docs/ads/aiads_interface/overview.md +++ b/docs/ads/aiads_interface/overview.md @@ -11,8 +11,8 @@ Interface is the layer that stands between the control team on software and the ```mermaid graph LR subgraph Ethernet - JT["Jetson"] - PI["Raspberry Pi"] + JT["Autonomous Software Stack Jetson"] + PI["Raspberry Pi/Jetson"] NT["Nanotec N5"] JT <--> PI PI <--> NT @@ -71,7 +71,7 @@ graph LR - 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. -### Raspberry Pi +### 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. \ No newline at end of file From 1eb60f45e475259faaed5ab273514ebdcead81d3 Mon Sep 17 00:00:00 2001 From: mbdalpha <166437418+mbdalpha@users.noreply.github.com> Date: Mon, 21 Sep 2026 07:39:28 +0100 Subject: [PATCH 5/6] add ASB page to nav --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 54fa858..3a4a093 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -134,6 +134,7 @@ nav: # This is the structure of the sidebar - AI/ADS Interface: - Overview: ads/aiads_interface/overview.md - Raspberry Pi Setup: ads/aiads_interface/raspberrypi.md + - Autonomous System Break: ads/aiads_interface/asb.md - Actuation Control: - Overview: ads/actuation_control/overview.md - Resources: From eb1fb537d6e5739c6a931c983c89223bc81ccfa9 Mon Sep 17 00:00:00 2001 From: mbdalpha <166437418+mbdalpha@users.noreply.github.com> Date: Thu, 24 Sep 2026 07:24:43 +0100 Subject: [PATCH 6/6] fix: remove break ESP as anyways ASB supervisor manages that --- docs/ads/aiads_interface/overview.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/ads/aiads_interface/overview.md b/docs/ads/aiads_interface/overview.md index 2697fe1..66a33d5 100644 --- a/docs/ads/aiads_interface/overview.md +++ b/docs/ads/aiads_interface/overview.md @@ -30,7 +30,6 @@ graph LR SE["Steering ESP"] CE["Clutch ESP"] GE["Gear ESP"] - BE["Break ESP"] HE["HMI ESP"] AHE["Auxillary Health ESP"] DS["DEWEsoft Logger"] @@ -44,14 +43,12 @@ graph LR SE .-> AS CE .-> AS GE .-> AS - BE .-> AS HE .-> AS ME .-> AS PK <--> TE PK <--> SE PK <--> CE PK <--> GE - PK <--> BE PK <--> HE PK <--> AHE PK <--> AS