oscc

Open Source Car Control (OSCC) is an assemblage of software and hardware designs that enable computer control of modern cars in order to facilitate the development of autonomous vehicle technology. It is a modular and stable way of using software to interface with a vehicle’s communications network and control systems.

OSCC enables developers to send control commands to the vehicle, read control messages from the vehicle’s OBD-II CAN network, and forward reports for current vehicle control state. Such as steering angle & wheel speeds. Control commands are issued to the vehicle component ECUs via the steering wheel torque sensor, throttle position sensor, and brake position sensor. (Because the gas-powered Kia Soul isn’t brake by-wire capable, an auxiliary actuator is added to enable braking.) This low-level interface means that OSCC offers full-range control of the vehicle without altering the factory safety-case, spoofing CAN messages, or hacking ADAS features.

Although OSCC currently supports only the 2014 or later Kia Soul (petrol and EV), the API and firmware have been designed to make it easy to add new vehicle support. Additionally, the separation between API and firmware means it is easier to modify and test parts of your program without having to update the flashed OSCC modules.

Our Wiki is in the process of being updated to reflect the new changes, but contains a bunch of valuable information to help you get started in understanding the details of the system.

DriveKit: If you're looking for a turn-key solution, we offer a commercially-supported vehicle control interface called DriveKit. DriveKit is a complete system for by-wire control of Kia Soul EV and Kia Niro Hybrid vehicles. It includes an integrated control module, automotive-grade wiring harnesses, e-stop switch, and additional vehicle control features –– plus it installs in under an hour. Visit https://polysync.io/drivekit/ for more information.

Versions

New versions of the API and the firmware are released periodically as new features are added and bugs are fixed. It is of vital importance that you update whenever there is a new version so that you can be certain you are not using a version with known safety issues.

There are four versions to be aware of:

• Sensor Interface Board (throttle and steering): the version is printed on the front of the shield

• Vehicle Control Module (EV brakes): the version is printed on the front of the shield

• Actuator Control Board (petrol brakes): the version is printed on the front of the shield

• API and Firmware: a single version is shared by both and listed in the Releases section of the repository.

The following table can be used to ensure that you use the appropriate firmware version with your boards:

* Later versions of the Actuator Control Board utilize new pins to perform additional safety checks on startup. To use the new firmware on older boards, please see additional instructions in the build section.

Repository Contents

• api - Software API, so your program can seamlessly talk to our modules.
• firmware - Arduino libraries and firmware for the OSCC modules.
• hardware - PCB schematics and board designs for control modules.

Boards

The sensor interface and actuator control board schematics and design files are located in the hardware/boards directory.

Thanks to Trey German for help designing the boards.

Building and Uploading Firmware

The OSCC Project is built around a number of individual firmware modules that inter-operate to allow communication with your vehicle. These modules are built from Arduinos and Arduino shields designed specifically for interfacing with various vehicle components. Once these modules have been installed in the vehicle and flashed with the firmware, the API can be used to receive reports from the car and send spoofed commands.

Pre-requisites

You must have Arduino Core (version 1.8.5 or greater) and CMake (version 2.8 or greater) installed on your machine.

sudo apt install build-essential cmake

A manual Arduino install is required since the debian package is older than 1.8.5

sudo apt-get purge arduino arduino-core
wget http://arduino.cc/download.php?f=/arduino-1.8.5-linux64.tar.xz -O arduino-1.8.5.tar.xz
tar -xf arduino-1.8.5.tar.xz
cd arduino-1.8.5
sudo mkdir -p /usr/share/arduino
sudo cp -R * /usr/share/arduino

OSCC uses CMake to avoid some of the limitations of the Arduino IDE. Using this method you can build and upload the firmware from the command-line.

Check out Arduino CMake for more information.

Building the Firmware

Navigate to the firmware directory and create a build directory inside of it:

cd firmware
mkdir build
cd build

To generate Makefiles, tell cmake which vehicle to build for by supplying the appropriate build flag:

For example, if you want to build firmware for the petrol Kia Soul:

cmake .. -DVEHICLE=kia_soul

Operator Overrides: While all OSCC modules have operator override detection enabled by default, attempting to grab the steering wheel while the system is active could result in serious injury. The preferred method of operator override for steering is to utilize the brake pedal or E-stop button. To disable operator override for the steering module, pass an additional flag to the CMake build step.

cmake .. -DVEHICLE=kia_soul -DSTEERING_OVERRIDE=OFF

If steering operator overrides remain enabled, the sensitivity can be adjusted by changing the value of the TORQUE_DIFFERENCE_OVERRIDE_THRESHOLD in the corresponding vehicle's header file.

• Lowering this value will make the steering module more sensitive to operator override, but will result in false positives around high-torque areas, such as the mechanical limits of the steering rack or when quickly and rapidly changing direction.
• Increasing this value will result in fewer false positives, but will make it more difficult to manually override the wheel.

By default, your firmware will have debug symbols which is good for debugging but increases the size of the firmware significantly. To compile without debug symbols and optimizations enabled, use the following instead:

cmake .. -DVEHICLE=kia_soul -DCMAKE_BUILD_TYPE=Release

NOTE:

For older ( The OSCC API catches the SIGIO signal which is asserted when a CAN frame is received on the CAN socket, and sets up a SIGIO signal handler to forward valid CAN messages to your application. If you have a section of code that is susceptible to conflicts with interrupts, you should temporarily block the SIGIO signal for the duration of that section and unblock it afterward.

Enable and disable all OSCC modules.

oscc_result_t oscc_enable( void );
oscc_result_t oscc_disable( void );

After you have initialized your CAN connection to the firmware modules, these methods can be used to enable or disable the system. This allows your application to choose when to enable sending commands to the firmware. Although you can only send commands when the system is enabled, you can receive reports at any time.

Publish control command to the corresponding module.

oscc_result_t publish_brake_position( double normalized_position );
oscc_result_t publish_steering_torque( double normalized_torque );
oscc_result_t publish_throttle_position( double normalized_position );

These commands will forward a double value to the specified firmware module. The double values are [0.0, 1.0] for brake and throttle, and [-1.0, 1.0] for steering where -1.0 is counterclockwise and 1.0 is clockwise. The API will construct the appropriate values to send as spoofed voltages to the vehicle to achieve the desired state. The API also contains safety checks to ensure no voltages outside of the vehicle's expected range are sent.

NOTE:

Each of these functions must be called at least once every 200ms to prevent the modules from detecting a loss of communication to the controlling computer (at which point they would disable themselves).

Register callback function to handle OSCC report and OBD messages.

oscc_result_t subscribe_to_brake_reports( void(*callback)(oscc_brake_report_s *report) );
oscc_result_t subscribe_to_steering_reports( void(*callback)(oscc_steering_report_s *report) );
oscc_result_t subscribe_to_throttle_reports( void(*callback)(oscc_throttle_report_s *report) );
oscc_result_t subscribe_to_fault_reports( void(*callback)(oscc_fault_report_s *report) );
oscc_result_t subscribe_to_obd_messages( void(*callback)(struct can_frame *frame) );

In order to receive reports from the modules, your application will need to register a callback handler with the OSCC API. When the appropriate report for your callback function is received from the API's socket connection, it will then forward the report to your software.

Each module's reports are described in their respective wiki sections:

• Brake (EV)
• Brake (Petrol)
• Steering
• Throttle

In addition to OSCC specific reports, it will also forward any non-OSCC reports to any callback function registered with subscribe_to_obd_messages. This can be used to view CAN frames received from the vehicle's OBD-II CAN channel. If you know the corresponding CAN frame's id, you can parse reports sent from the car.

Tests

There are two types of tests available: unit and property-based.

Test Dependencies

The unit tests and property-based tests each have their own set of dependencies required to run the tests.

For the unit tests you must have Cucumber 2.0.0 and its dependency Boost installed:

sudo apt install ruby-dev libboost-dev
sudo gem install cucumber -v 2.0.0

For the property-based tests you must have Rust, its build manager Cargo, and libclang:

sudo apt install rustc cargo clang libclang-dev

Running Tests

Building and running the tests is similar to the firmware itself, but you must instead tell cmake to build the tests instead of the firmware with the -DTESTS=ON flag. We also pass the -DCMAKE_BUILD_TYPE=Release flag so that cmake will disable debug symbols and enable optimizations, good things to do when running tests to ensure nothing breaks with optimizations. Lastly, you must tell the tests which vehicle header to use for the tests (e.g., -DVEHICLE=kia_soul).

cd firmware
mkdir build
cd build
cmake .. -DTESTS=ON -DCMAKE_BUILD_TYPE=Release -DVEHICLE=kia_soul

Unit Tests

Each module has a suite of unit tests that use Cucumber with Cgreen. There are pre-built 64-bit Linux versions in firmware/common/testing/framework.

Boost is required for Cucumber-CPP and has been statically linked into libcucumber-cpp.a. If you need to build your own versions you can use the provided script build_test_framework.sh which will install the Boost dependencies (needed for bu