fix

docs/CONTRIBUTING.md

@@ -6,21 +6,20 @@ Development is coordinated through [Discord](https://discord.comma.ai) and GitHu
 
 ### Getting Started
 
-* Setup your [development environment](../tools/)
-* Read about the [development workflow](WORKFLOW.md)
+* Set up your [development environment](/tools/)
 * Join our [Discord](https://discord.comma.ai)
 * Docs are at https://docs.comma.ai and https://blog.comma.ai
 
 ## What contributions are we looking for?
 
 **openpilot's priorities are [safety](SAFETY.md), stability, quality, and features, in that order.**
-openpilot is part of comma's mission to *solve self-driving cars while delivering shippable intermediaries*, and all development is towards that goal. 
+openpilot is part of comma's mission to *solve self-driving cars while delivering shippable intermediaries*, and all development is towards that goal.
 
 ### What gets merged?
 
 The probability of a pull request being merged is a function of its value to the project and the effort it will take us to get it merged.
 If a PR offers *some* value but will take lots of time to get merged, it will be closed.
-Simple, well-tested bug fixes are the easiest to merge, and new features are the hardest to get merged. 
+Simple, well-tested bug fixes are the easiest to merge, and new features are the hardest to get merged.
 
 All of these are examples of good PRs:
 * typo fix: https://github.com/commaai/openpilot/pull/30678
@@ -30,17 +29,17 @@ All of these are examples of good PRs:
 
 ### What doesn't get merged?
 
-* **style changes**: code is art, and it's up to the author to make it beautiful 
+* **style changes**: code is art, and it's up to the author to make it beautiful
 * **500+ line PRs**: clean it up, break it up into smaller PRs, or both
 * **PRs without a clear goal**: every PR must have a singular and clear goal
 * **UI design**: we do not have a good review process for this yet
 * **New features**: We believe openpilot is mostly feature-complete, and the rest is a matter of refinement and fixing bugs. As a result of this, most feature PRs will be immediately closed, however the beauty of open source is that forks can and do offer features that upstream openpilot doesn't.
-* **Negative expected value**: This a class of PRs that makes an improvement, but the risk or validation costs more than the improvement. The risk can be mitigated by first getting a failing test merged.
+* **Negative expected value**: This is a class of PRs that makes an improvement, but the risk or validation costs more than the improvement. The risk can be mitigated by first getting a failing test merged.
 
 ### First contribution
 
 [Projects / openpilot bounties](https://github.com/orgs/commaai/projects/26/views/1?pane=info) is the best place to get started and goes in-depth on what's expected when working on a bounty.
-There's lot of bounties that don't require a comma 3/3X or a car.
+There are a lot of bounties that don't require a comma four or a car.
 
 ## Pull Requests
 

docs/DEBUGGING_SAFETY.md

@@ -0,0 +1,30 @@
+# Debugging Panda Safety with Replay Drive + LLDB
+
+## 1. Start the debugger in VS Code
+
+* Select **Replay drive + Safety LLDB**.
+* Enter the route or segment when prompted.
+[<img src="https://github.com/user-attachments/assets/b0cc320a-083e-46a7-a9f8-ca775bbe5604">](https://github.com/user-attachments/assets/b0cc320a-083e-46a7-a9f8-ca775bbe5604)
+
+## 2. Attach LLDB
+
+* When prompted, pick the running **`replay_drive` process**.
+* ⚠️ Attach quickly, or `replay_drive` will start consuming messages.
+
+> [!TIP]
+> Add a Python breakpoint at the start of `replay_drive.py` to pause execution and give yourself time to attach LLDB.
+
+## 3. Set breakpoints in VS Code
+Breakpoints can be set directly in `modes/xxx.h` (or any C file).
+No extra LLDB commands are required — just place breakpoints in the editor.
+
+## 4. Resume execution
+Once attached, you can step through both Python (on the replay) and C safety code as CAN logs are replayed.
+
+> [!NOTE]
+> * Use short routes for quicker iteration.
+> * Pause `replay_drive` early to avoid wasting log messages.
+
+## Video
+
+View a demo of this workflow on the PR that added it: https://github.com/commaai/openpilot/pull/36055#issue-3352911578

docs/README.md

@@ -8,7 +8,7 @@ NOTE: Those commands must be run in the root directory of openpilot, **not /docs
 
 **1. Install the docs dependencies**
 ``` bash
-pip install .[docs]
+uv pip install .[docs]
 ```
 
 **2. Build the new site**

docs/SAFETY.md

@@ -16,7 +16,7 @@ industry standards of safety for Level 2 Driver Assistance Systems. In particula
 ISO26262 guidelines, including those from [pertinent documents](https://www.nhtsa.gov/sites/nhtsa.dot.gov/files/documents/13498a_812_573_alcsystemreport.pdf)
 released by NHTSA. In addition, we impose strict coding guidelines (like [MISRA C : 2012](https://www.misra.org.uk/what-is-misra/))
 on parts of openpilot that are safety relevant. We also perform software-in-the-loop,
-hardware-in-the-loop and in-vehicle tests before each software release.
+hardware-in-the-loop, and in-vehicle tests before each software release.
 
 Following Hazard and Risk Analysis and FMEA, at a very high level, we have designed openpilot
 ensuring two main safety requirements.
@@ -25,12 +25,22 @@ ensuring two main safety requirements.
    by stepping on the brake pedal or by pressing the cancel button.
 2. The vehicle must not alter its trajectory too quickly for the driver to safely
    react. This means that while the system is engaged, the actuators are constrained
-   to operate within reasonable limits[^1]. 
+   to operate within reasonable limits[^1].
 
-For additional safety implementation details, refer to [panda safety model](https://github.com/commaai/panda#safety-model). For vehicle specific implementation of the safety concept, refer to [panda/board/safety/](https://github.com/commaai/panda/tree/master/board/safety).
+For additional safety implementation details, refer to [panda safety model](https://github.com/commaai/panda#safety-model). For vehicle specific implementation of the safety concept, refer to [opendbc/safety/safety](https://github.com/commaai/opendbc/tree/master/opendbc/safety/safety).
 
-**Extra note**: comma.ai strongly discourages the use of openpilot forks with safety code either missing or
-  not fully meeting the above requirements.
+[^1]: For these actuator limits we observe ISO11270 and ISO15622. Lateral limits described there translate to 0.9 seconds of maximum actuation to achieve a 1m lateral deviation.
 
-[^1]: For these actuator limits we observe ISO11270 and ISO15622. Lateral limits described there translate to 0.9 seconds of maximum actuation to achieve a 1m lateral deviation. 
+---
 
+### Forks of openpilot
+
+* Do not disable or nerf [driver monitoring](https://github.com/commaai/openpilot/tree/master/selfdrive/monitoring)
+* Do not disable or nerf [excessive actuation checks](https://github.com/commaai/openpilot/tree/master/selfdrive/selfdrived/helpers.py)
+* If your fork modifies any of the code in `opendbc/safety/`:
+   * your fork cannot use the openpilot trademark
+   * your fork must preserve the full [safety test suite](https://github.com/commaai/opendbc/tree/master/opendbc/safety/tests) and all tests must pass, including any new coverage required by the fork's changes
+
+Failure to comply with these standards will get you and your users banned from comma.ai servers.
+
+**comma.ai strongly discourages the use of openpilot forks with safety code either missing or not fully meeting the above requirements.**

docs/car-porting/car-state-signals.md

@@ -0,0 +1,65 @@
+# CarState signals
+
+## Required for basic lateral control
+
+* `brakePressed`
+* `cruiseState`
+* `doorOpen`
+* `espDisabled`
+* `gasPressed`
+* `gearShifter`
+* `leftBlinker` / `rightBlinker`
+* `seatbeltUnlatched`
+* `standstill`
+* `steeringAngleDeg`
+* `steeringPressed`
+* `steeringTorque`
+* `steerFaultPermanent`
+* `steerFaultTemporary`
+* `vCruise`
+* `wheelSpeeds.[fl|fr|rl|rr]`: Speed of each of the car's four wheels, in m/s. The car's CAN bus often broadcasts the
+speed in kph, so the helper function `parse_wheel_speeds` performs this conversion by default.
+
+## Recommended / Required for openpilot longitudinal control
+
+* `accFaulted`
+* `espActive`
+* `parkingBrake`
+
+## Application Dependent
+
+* `blockPcmEnable`
+* `buttonEnable`
+* `brakeHoldActive`
+* `carFaultedNonCritical`
+* `invalidLkasSetting`
+* `lowSpeedAlert`
+* `regenBraking`
+* `steeringAngleOffsetDeg`
+* `steeringDisengage`
+* `steeringTorqueEps`
+* `stockLkas`
+* `vCruiseCluster`
+* `vEgoCluster`
+* `vehicleSensorsInvalid`
+
+## Automatically populated
+
+* `buttonEvents`
+
+These values are populated automatically by `parse_wheel_speeds`:
+
+* `aEgo`: Acceleration of the ego vehicle, Kalman filtered derivative of `vEgo`.
+* `vEgo`: Speed of the ego vehicle, Kalman filtered from `vEgoRaw`.
+* `vEgoRaw`: Speed of the ego vehicle, based on the average of all four wheel speeds, unfiltered.
+
+## Optional
+
+* `brake`
+* `charging`
+* `fuelGauge`
+* `leftBlindspot` / `rightBlindspot`
+* `steeringRateDeg`
+* `stockAeb`
+* `stockFcw`
+* `yawRate`

docs/car-porting/reverse-engineering.md

@@ -0,0 +1,85 @@
+# Stimulus-Response Tests
+
+These are example test drives that can help identify the CAN bus messaging necessary for ADAS control. Each scripted
+test should be done in a separate route (ignition cycle). These tests are a guide, not necessarily exhaustive.
+
+While testing, constant power to the comma device is highly recommended, using [comma power](https://comma.ai/shop/comma-power) if
+necessary to make sure all test activity is fully captured and for ease of uploading. If constant power isn't
+available, keep the ignition on for at least one minute after your test to make sure power loss doesn't result
+in loss of the last minute of testing data.
+
+## Stationary ignition-only tests, part 1
+
+1. Ignition on, but don't start engine, remain in Park
+2. Open and close each door in a defined order: driver, passenger, rear left, rear right
+3. Re-enter the vehicle, close the driver's door, and fasten the driver's seatbelt
+4. Slowly press and release the accelerator pedal 3 times
+5. Slowly press and release the brake pedal 3 times
+6. Hold the brake and move the gearshift to reverse, then neutral, then drive, then sport/eco/etc if applicable
+7. Return to Park, ignition off
+
+Brake-pressed information may show up in several messages and signals, both as on/off states and as a percentage or
+pressure. It may reflect a switch on the driver's brake pedal, or a pressure-threshold state, or signals to turn on
+the rear brake lights. Start by identifying all the potential signals, and confirm while driving with ACC later.
+
+Locate signals for all four door states if possible, but some cars only expose the driver's door state on the ADAS bus.
+Driver/passenger door signals may or may not change positions for LHD vs RHD cars. For cars where only the driver's
+door signal is available, the same signal may follow the driver.
+
+## Stationary ignition-only tests, part 2
+
+1. Ignition on, but don't start engine, remain in Park
+2. Press each ACC button in a defined order: main switch on/off, set, resume, cancel, accel, decel, gap adjust
+3. Set the left turn signal for about five seconds
+4. Operate the left turn signal one time in its touch-to-pass mode
+5. Set the right turn signal for about five seconds
+6. Operate the right turn signal one time in its touch-to-pass mode
+7. Set the hazard / emergency indicator switch for about five seconds
+8. Ignition off
+
+Your vehicle may have a momentary-press main ACC switch or a physical toggle that remains set. Actual ACC engagement
+isn't necessary for purposes of detecting the ACC button presses.
+
+## Steering angle and steering torque tests
+
+Power steering should be available. On ICE cars, engine RPM may be present.
+
+1. Ignition on, start engine if applicable, remain in Park
+2. Rotate the steering wheel as follows, with a few seconds pause between each step
+   * Start as close to exact center as possible
+   * Turn to 45 degrees right and hold
+   * Turn to 90 degrees right and hold
+   * Turn to 180 degrees right and hold
+   * Turn to full lock right and hold, with firm pressure against lock
+   * Release the wheel and allow it to bounce back slightly from lock
+   * Turn to 180 degrees left and hold
+   * Return to center and release
+3. Ignition off
+
+Performing the full test to the right, followed by an abbreviated test to the left, helps give additional confirmation
+of signal scale, and sign/direction for both the steering wheel angle and driver input torque signals.
+
+## Low speed / parking lot driving tests
+
+Before this test, drive to a place like an empty parking lot where you are free to drive in a series of curves.
+
+1. Ignition on, start engine if applicable, prepare to drive
+2. Slowly (10-20mph at most) drive a figure-8 if possible, or at least one sharp left and one sharp right.
+3. Come to a complete stop
+4. When and where safe, drive in reverse for a short distance (10-15 feet)
+5. Park the car in a safe place, ignition off
+
+## High speed / highway driving tests
+
+Select a place and time where you can safely set cruise control at normal travel speeds with little interference from
+traffic ahead, and safely test the response of your factory lane guidance system.
+
+1. Ignition on, start engine if applicable, prepare to drive
+2. When safely able, engage adaptive cruise control below 50 mph
+3. When safely able, use the ACC buttons to accelerate to 50mph, then 55mph, then 60mph
+4. Disengage adaptive cruise
+5. When safely able, allow your factory lane guidance to prevent lane departures, 2-3 times on both the left and right
+
+The series of setpoints can be adjusted to local traffic regulations, and of course metric units. The specific cruise
+setpoints are useful for locating the ACC HUD signals later, and confirming their precise scaling. When the car reaches
+and holds the setpoint, that can also provide additional confirmation of wheel speed scaling.

docs/car-porting/what-is-a-car-port.md

@@ -21,10 +21,10 @@ Each car brand is supported by a standard interface structure in `opendbc/car/[b
 * `values.py`: Limits for actuation, general constants for cars, and supported car documentation
 * `radar_interface.py`: Interface for parsing radar points from the car, if applicable
 
-## panda
+## safety
 
-* `board/safety/safety_[brand].h`: Brand-specific safety logic
-* `tests/safety/test_[brand].py`: Brand-specific safety CI tests
+* `opendbc_repo/opendbc/safety/modes/[brand].h`: Brand-specific safety logic
+* `opendbc_repo/opendbc/safety/tests/test_[brand].py`: Brand-specific safety CI tests
 
 ## openpilot
 

docs/concepts/glossary.md

@@ -6,4 +6,4 @@
 * **segment**: routes are split into one minute chunks called segments.
 * **comma connect**: the web viewer for all your routes; check it out at [connect.comma.ai](https://connect.comma.ai).
 * **panda**: this is the secondary processor on the device that implements the functional safety and directly talks to the car over CAN. See the [panda repo](https://github.com/commaai/panda).
-* **comma 3X**: the latest hardware by comma.ai for running openpilot. more info at [comma.ai/shop](https://comma.ai/shop).
+* **comma four**: the latest hardware by comma.ai for running openpilot. more info at [comma.ai/shop/comma-four](https://www.comma.ai/shop/comma-four).

docs/contributing/roadmap.md

@@ -12,7 +12,7 @@ This is the roadmap for the next major openpilot releases. Also check out
 openpilot 0.10 will be the first release with a driving policy trained in
 a [learned simulator](https://youtu.be/EqQNZXqzFSI).
 
-* Driving model trained in a learned simlator
+* Driving model trained in a learned simulator
 * Always-on driver monitoring (behind a toggle)
 * GPS removed from the driving stack
 * 100KB qlogs

docs/getting-started/what-is-openpilot.md

@@ -5,7 +5,7 @@
 
 ## How do I use it?
 
-openpilot is designed to be used on the comma 3X.
+openpilot is designed to be used on the comma four.
 
 ## How does it work?
 

docs/how-to/connect-to-comma.md

@@ -1,15 +1,15 @@
-# connect to a comma 3/3X
+# connect to a comma four
 
-A comma 3/3X is a normal [Linux](https://github.com/commaai/agnos-builder) computer that exposes [SSH](https://wiki.archlinux.org/title/Secure_Shell) and a [serial console](https://wiki.archlinux.org/title/Working_with_the_serial_console).
+A comma four is a normal [Linux](https://github.com/commaai/agnos-builder) computer that exposes [SSH](https://wiki.archlinux.org/title/Secure_Shell) and a [serial console](https://wiki.archlinux.org/title/Working_with_the_serial_console).
 
 ## Serial Console
 
-On both the comma three and 3X, the serial console is accessible from the main OBD-C port.
-Connect the comma 3/3X to your computer with a normal USB C cable, or use a [comma serial](https://comma.ai/shop/comma-serial) for steady 12V power.
+On both the comma three and comma four, the serial console is accessible from the main OBD-C port.
+Connect the comma four to your computer with a normal USB C cable, or use a [comma serial](https://comma.ai/shop/comma-serial) for steady 12V power.
 
 On the comma three, the serial console is exposed through a UART-to-USB chip, and `tools/scripts/serial.sh` can be used to connect.
 
-On the comma 3X, the serial console is accessible through the [panda](https://github.com/commaai/panda) using the `panda/tests/som_debug.sh` script.
+On the comma four, the serial console is accessible through the [panda](https://github.com/commaai/panda) using the `panda/tests/som_debug.sh` script.
 
   * Username: `comma`
   * Password: `comma`
@@ -32,16 +32,20 @@ For doing development work on device, it's recommended to use [SSH agent forward
 
 ## ADB
 
-In order to use ADB on your device, you'll need to enable it in the device's settings.
+In order to use ADB on your device, you'll need to perform the following steps using the image below for reference:
 
+![comma 3/3x back](../assets/three-back.svg)
+
+* Plug your device into constant power using port 2, letting the device boot up
 * Enable ADB in your device's settings
+* Plug in your device to your PC using port 1
 * Connect to your device
     * `adb shell` over USB
     * `adb connect` over WiFi
     * Here's an example command for connecting to your device using its tethered connection: `adb connect 192.168.43.1:5555`
 
 > [!NOTE]
-> The default port for ADB is 5555 on the comma 3/3X.
+> The default port for ADB is 5555 on the comma four.
 
 For more info on ADB, see the [Android Debug Bridge (ADB) documentation](https://developer.android.com/tools/adb).