sunnypilot Documentation

The tools/ directory contains various utilities for interacting with openpilot, including visualization, simulation, and hardware control:

• cabana/: View and plot CAN messages from drives or in realtime.
• camerastream/: Cameras stream over the network.
• joystick/: Control your car with a joystick.
• lib/: Libraries to support the tools and reading openpilot logs.
• plotjuggler/: A tool to plot openpilot logs.
• replay/: Replay drives and mock openpilot services.
• scripts/: Miscellaneous scripts.
• serial/: Tools for using the comma serial.
• sim/: Run openpilot in a simulator.
• webcam/: Run openpilot on a PC with webcams.

sunnypilot (based on openpilot) is an open source driver assistance system. It provides several Advanced Driver Assistance System (ADAS) functions, including:

• Adaptive Cruise Control (ACC): Manages vehicle speed and following distance.
• Automated Lane Centering (ALC): Assists with steering to keep the vehicle in its lane.
• Forward Collision Warning (FCW): Alerts the driver to potential frontal collisions.
• Lane Departure Warning (LDW): Alerts the driver if the vehicle drifts from its lane.
• Driver Monitoring (DM): A camera-based feature that alerts distracted or asleep drivers while the system is engaged.

The system works by utilizing the car's existing APIs for its built-in ADAS and providing improved acceleration, braking, and steering inputs compared to the stock system.

The joystick_control tool allows you to connect a laptop to a comma device over a network to debug vehicle controls using a joystick or a keyboard. It uses the inputs library to support various gamepads and joysticks.

Prerequisites:

• A device running openpilot.
• A laptop.
• A joystick (optional).
• Crucial: The car must be off and openpilot must be offroad before starting joystick_control.

sunnypilot uses Quaternions, rotation matrices, and Euler angles.

Euler Angles

• Convention: [roll, pitch, yaw] corresponding to rotations around [x, y, z] axes.
• Units: Always use radians or radians/s (except for display/plotting).
• Rotation Order: To rotate from one frame to another, rotate around roll, then pitch, then yaw, using intrinsic rotations (rotating around the rotated axes, not the original axes).

Quaternions

• Convention: Hamilton notation [qw, qx, qy, qz].
• Requirements: All quaternions must be normalized and have a strictly positive qw to ensure a unique representation of orientation.

When porting openpilot to a new vehicle, the complexity depends on whether you are introducing a new brand or a new model within an existing brand.

• Brand Port: A port to a substantially new car brand or a new platform within an existing brand. This is more complex as the architecture and APIs are unknown.
• Model Port: A port to a new car model within an already supported brand. These are generally easier because the car's existing APIs and communication structures are already known to the system.

You can define reusable rule fragments in settings_ui_src/_macros.yaml and reference them in your page YAML files. This is useful for common constraints like offroad_only or platform-specific gates.

Defining a Macro

In _macros.yaml:

macros:
  offroad: [{type: offroad_only}]
  longitudinal: [{type: capability, field: has_longitudinal_control, equals: true}]

Referencing a Macro

In a page YAML file, use the {$ref: "#/macros/<name>"} syntax within an enablement array:

enablement:
  - {$ref: "#/macros/offroad"}
  - {$ref: "#/macros/longitudinal"}

Constraints:

• The compiler splices the macro's list into the parent list.
• Macros can reference other macros up to a depth of 3.
• Circular references will cause a compiler error.