Skip to content

Commit b9e4fc4

Browse files
rubenaylaclaude
rubenayla
and
claude
committed
Add state machine docs, AS state reference, and FS rules PDFs
- docs/software/state_machine.md: Full state machine documentation with mermaid diagram, mux logic table, transition details, ROS topics - docs/rules/as_state_machine.md: FS T14.8 AS state decision tree reference - docs/rules/: FS Rules 2026, FS-AI 2025, FS-AI 2026 APC rules PDFs - mkdocs.yml: Add mermaid support and state machine nav entry Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 1fe3889 commit b9e4fc4

6 files changed

Lines changed: 260 additions & 1 deletion

File tree

‎docs/rules/FS-AI_2025_Rules_v1.0.pdf‎

467 KB
Binary file not shown.

‎docs/rules/FS-AI_2026_APC_Technical_Rules_v1.pdf‎

876 KB
Binary file not shown.

‎docs/rules/FS-Rules_2026_v1.1.pdf‎

884 KB
Binary file not shown.

‎docs/rules/as_state_machine.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# AS (Autonomous System) State Machine
2+
3+
Reference: FS Rules 2026 v1.1, Section T14.8, Figure 15 (page 68)
4+
5+
## States
6+
7+
| State | ASSI Color | Description |
8+
|-------|-----------|-------------|
9+
| AS Off | off | System inactive, no autonomous capability |
10+
| AS Ready | yellow continuous | Mission selected, all checks passed, brakes engaged, waiting for RES Go |
11+
| AS Driving | yellow flashing (2-5 Hz) | Vehicle is in R2D, autonomous driving active |
12+
| AS Finished | blue continuous | Mission completed, vehicle at standstill |
13+
| AS Emergency | blue flashing (2-5 Hz) | EBS activated, emergency state |
14+
15+
## State Determination (Figure 15 - Continuous Decision Tree)
16+
17+
The AS status is **continuously evaluated** based on current conditions, not discrete event-driven transitions:
18+
19+
```
20+
Entry → EBS activated?
21+
├─ YES → Mission finished AND Vehicle at Standstill?
22+
│ ├─ YES → SDC open at RES?
23+
│ │ ├─ YES → AS Emergency
24+
│ │ └─ NO → AS Finished
25+
│ └─ NO → AS Emergency
26+
└─ NO → Mission Selected AND ASMS On AND ASB checks OK AND TS Active?
27+
├─ NO → AS Off
28+
└─ YES → R2D (Ready-to-Drive)?
29+
├─ YES → AS Driving
30+
└─ NO → Brakes engaged?
31+
├─ YES → AS Ready
32+
└─ NO → AS Off
33+
```
34+
35+
## Key Timing Requirements
36+
37+
- **T14.8.4**: R2D mode may only be entered by the RES "Go" signal, after the system has remained in "AS Ready" for **at least 5 seconds**
38+
- **T14.8.5**: The vehicle must not start moving until the system has remained in "AS Driving" for **at least 3 seconds**
39+
40+
## Conditions for Each State
41+
42+
### AS Off
43+
- EBS not activated AND (no mission selected OR ASMS off OR ASB checks failed OR TS not active OR brakes not engaged)
44+
45+
### AS Ready
46+
- EBS not activated AND mission selected AND ASMS on AND ASB checks OK AND TS active AND brakes engaged AND NOT in R2D
47+
48+
### AS Driving
49+
- EBS not activated AND all AS Ready conditions met AND R2D active (via RES Go after 5s in AS Ready)
50+
51+
### AS Finished
52+
- EBS activated AND mission finished AND vehicle at standstill AND SDC NOT open at RES
53+
54+
### AS Emergency
55+
- EBS activated AND (vehicle not at standstill OR mission not finished OR SDC open at RES)
56+
57+
## Required Missions (T14.10)
58+
59+
- Acceleration
60+
- Skidpad
61+
- Autocross (DC only)
62+
- Trackdrive (DC only)
63+
- EBS Test
64+
- Inspection
65+
- Manual Driving
66+
67+
## Hardware Interfaces
68+
69+
- **RES (Remote Emergency System)**: Physical remote with Go button and emergency stop (T14.3)
70+
- **ASMS (Autonomous System Master Switch)**: Physical rotary switch, must have lockout/tagout (T14.5)
71+
- **ASSI (Autonomous System Status Indicator)**: 3x lights showing AS state (T14.9)
72+
- **AMI (Autonomous Mission Indicator)**: Displays selected mission, readable from outside (T14.10)
73+
- **ASB (Autonomous System Brake)**: Emergency braking with EBS (T15)
74+
75+
## Our Implementation Notes
76+
77+
Our kart (APC entry) doesn't have all the ADS-DV hardware (no physical RES, no ASMS switch).
78+
We simulate these via dashboard buttons. The state machine in `state_machine_node.py` maps:
79+
80+
- Dashboard "start" button → RES "Go" signal
81+
- Dashboard "stop" button → equivalent to ASMS off (returns to AS Off)
82+
- Dashboard "ebs" button → EBS activation (AS Emergency)
83+
- Dashboard mission selector → mission selection + simulated ASMS on
84+
85+
The 5s AS_READY wait and 3s AS_DRIVING delay are NOT currently implemented but are
86+
required for competition compliance.

‎docs/software/state_machine.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# State Machine
2+
3+
The state machine node (`state_machine_node.py`) is the central safety and control authority for the kart. It determines what drives the wheels by muxing `cmd_vel` based on two independent variables: the **mission** (what the kart should do) and the **AS state** (whether the autonomous system is allowed to drive).
4+
5+
**Source:** `src/kart_bringup/scripts/state_machine_node.py`
6+
7+
---
8+
9+
## Two Independent Variables
10+
11+
### Mission
12+
13+
The **mission** is selected from the dashboard. It determines the operating mode:
14+
15+
| Mission | Type | Description |
16+
|---------|------|-------------|
17+
| `manual` | Manual | Direct control via joystick/dashboard |
18+
| `remote_control` | Manual | Same as manual (dashboard remote) |
19+
| `throttle_test` | Test | Fixed 50% throttle for hardware debugging |
20+
| `acceleration` | Autonomous | FS acceleration event |
21+
| `skidpad` | Autonomous | FS skidpad event |
22+
| `autocross` | Autonomous | FS autocross event |
23+
| `trackdrive` | Autonomous | FS trackdrive event |
24+
| `ebs_test` | Autonomous | Emergency braking system test |
25+
| `inspection` | Autonomous | Technical inspection demo |
26+
27+
### AS State (Autonomous System State)
28+
29+
The **AS state** tracks the autonomous system lifecycle per Formula Student rules (T14.8):
30+
31+
| State | ID | Description |
32+
|-------|----|-------------|
33+
| `AS_OFF` | 0 | Autonomous system inactive |
34+
| `AS_READY` | 1 | Armed and waiting for "Go" signal |
35+
| `AS_DRIVING` | 2 | Autonomous driving active |
36+
| `AS_FINISHED` | 3 | Mission complete, vehicle stopped |
37+
| `AS_EMERGENCY` | 4 | Emergency braking activated |
38+
39+
---
40+
41+
## cmd_vel Mux Logic
42+
43+
The state machine selects which velocity command reaches the actuators:
44+
45+
| Mission | AS State | Output | Why |
46+
|---------|----------|--------|-----|
47+
| `manual` / `remote_control` | *any* | Manual cmd_vel | Operator has direct control |
48+
| `throttle_test` | *any* | Fixed 50% throttle | Hardware test, no perception |
49+
| Any autonomous | `AS_DRIVING` | Autonomous cmd_vel | Controller drives the kart |
50+
| Any autonomous | *anything else* | Zero (stopped) | Safety: no motion unless AS_DRIVING |
51+
52+
!!! info "Key insight"
53+
AS state only matters for autonomous missions. Manual and throttle_test bypass it entirely -- the operator is always in control.
54+
55+
---
56+
57+
## State Transitions
58+
59+
```mermaid
60+
stateDiagram-v2
61+
classDef off fill:#6c757d,color:#fff
62+
classDef ready fill:#ffc107,color:#000
63+
classDef driving fill:#28a745,color:#fff
64+
classDef finished fill:#17a2b8,color:#fff
65+
classDef emergency fill:#dc3545,color:#fff
66+
67+
[*] --> AS_OFF
68+
69+
AS_OFF --> AS_READY : Select autonomous mission
70+
AS_READY --> AS_DRIVING : "start" command
71+
AS_DRIVING --> AS_FINISHED : "finish" command
72+
AS_DRIVING --> AS_READY : "stop" (auto mission)
73+
AS_READY --> AS_OFF : Switch to manual
74+
75+
AS_FINISHED --> AS_OFF : "reset" command
76+
AS_EMERGENCY --> AS_OFF : "reset" command
77+
78+
AS_READY --> AS_EMERGENCY : "ebs" command
79+
AS_DRIVING --> AS_EMERGENCY : "ebs" command
80+
AS_FINISHED --> AS_EMERGENCY : "ebs" command
81+
82+
AS_DRIVING --> AS_READY : Select new auto mission
83+
AS_FINISHED --> AS_READY : Select new auto mission
84+
85+
class AS_OFF off
86+
class AS_READY ready
87+
class AS_DRIVING driving
88+
class AS_FINISHED finished
89+
class AS_EMERGENCY emergency
90+
```
91+
92+
### Transition Details
93+
94+
| Trigger | From | To | Notes |
95+
|---------|------|----|-------|
96+
| Select autonomous mission | `AS_OFF`, `AS_DRIVING`, `AS_FINISHED` | `AS_READY` | Auto-arms the system |
97+
| Switch to manual | Any (except `AS_OFF`) | `AS_OFF` | Fully disarms |
98+
| `start` | `AS_READY` | `AS_DRIVING` | Begin autonomous driving |
99+
| `stop` (auto mission active) | `AS_READY`, `AS_DRIVING`, `AS_FINISHED`, `AS_EMERGENCY` | `AS_READY` | Stays armed |
100+
| `stop` (manual mission) | Any | `AS_OFF` | Fully disarms |
101+
| `ebs` | Any (except `AS_OFF`) | `AS_EMERGENCY` | Emergency braking |
102+
| `finish` | `AS_DRIVING` | `AS_FINISHED` | Mission complete |
103+
| `reset` | `AS_FINISHED`, `AS_EMERGENCY` | `AS_OFF` | Clear error/completion |
104+
105+
---
106+
107+
## ASSI (Autonomous System Status Indicator)
108+
109+
The ASSI communicates the AS state visually, as required by FS rules:
110+
111+
| State | ASSI Signal |
112+
|-------|-------------|
113+
| `AS_OFF` | Off |
114+
| `AS_READY` | Yellow continuous |
115+
| `AS_DRIVING` | Yellow flashing (2-5 Hz) |
116+
| `AS_FINISHED` | Blue continuous |
117+
| `AS_EMERGENCY` | Blue flashing (2-5 Hz) |
118+
119+
---
120+
121+
## Formula Student Competition Context
122+
123+
These states map to the **FS T14.8 AS Status** (Figure 15 in FS Rules 2026). See also the [rules reference](../rules/as_state_machine.md) for the full FS decision tree and hardware requirements.
124+
125+
In a real competition, additional checks gate each transition:
126+
127+
- **AS_READY** requires: mission selected + ASMS on + ASB checks OK + TS active + brakes engaged
128+
- **AS_DRIVING** (R2D) is triggered only via the RES (Remote Emergency System) "Go" signal, after 5 seconds in AS_READY
129+
- The vehicle must not move until 3 seconds after entering AS_DRIVING
130+
131+
!!! warning "Current limitations"
132+
We simulate the RES "Go" signal with the dashboard "start" button since we don't have RES hardware yet. The 5-second AS_READY hold time and the 3-second AS_DRIVING standstill requirement are **not yet implemented**.
133+
134+
---
135+
136+
## ROS Topics
137+
138+
### Subscriptions (inputs)
139+
140+
| Topic | Type | Source | Purpose |
141+
|-------|------|--------|---------|
142+
| `/dashboard/mission` | `String` | Dashboard | Mission selection |
143+
| `/dashboard/state_cmd` | `String` | Dashboard | Commands: start, stop, ebs, finish, reset |
144+
| `/kart/cmd_vel` | `Twist` | Controller | Autonomous velocity command |
145+
| `/kart/cmd_vel_manual` | `Twist` | Joystick / Dashboard | Manual velocity command |
146+
147+
### Publications (outputs)
148+
149+
| Topic | Type | Rate | Purpose |
150+
|-------|------|------|---------|
151+
| `/kart/cmd_vel_muxed` | `Twist` | 100 Hz | Final muxed velocity command |
152+
| `/kart/state` | `String` | 10 Hz | Current AS state name (heartbeat) |
153+
| `/orin/machine_state` | `Frame` | On change | AS state ID to ESP32 |
154+
| `/orin/mision` | `Frame` | On change | Mission ID to ESP32 |
155+
| `/orin/steer_mode` | `Frame` | On change | Steering mode (PID/PWM) to ESP32 |
156+
157+
---
158+
159+
## Implementation Notes
160+
161+
The node runs two timers:
162+
163+
- **100 Hz mux timer** (`_mux_tick`): Reads the current mission and state, selects the appropriate `cmd_vel` source, and publishes to `/kart/cmd_vel_muxed`.
164+
- **10 Hz heartbeat** (`_publish_state`): Publishes the current state name so other nodes and the dashboard can monitor it.
165+
166+
State transitions are triggered by ROS topic callbacks, not by the timers. Each transition logs the change and publishes the new state to both ROS topics and ESP32 frames.
167+
168+
When an autonomous mission is selected, the node forces PID steering mode via `/orin/steer_mode` to ensure the ESP32 uses closed-loop steering control.

‎mkdocs.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@ theme:
66
markdown_extensions:
77
- admonition
88
- pymdownx.details
9-
- pymdownx.superfences
9+
- pymdownx.superfences:
10+
custom_fences:
11+
- name: mermaid
12+
class: mermaid
13+
format: !!python/name:pymdownx.superfences.fence_code_format
1014
nav:
1115
- Home: index.md
1216
- About: about.md
@@ -42,6 +46,7 @@ nav:
4246
- Hydraulics: hydraulics/index.md
4347
- Software:
4448
- software/index.md
49+
- State Machine: software/state_machine.md
4550
- 2024 — Python: software/legacy.md
4651
- 2025 — ROS 2:
4752
- software/ros2/index.md

0 commit comments

Comments
 (0)