{"id":13784839,"url":"https://github.com/PolySync/OSCC","last_synced_at":"2025-05-11T20:31:23.540Z","repository":{"id":114826837,"uuid":"73134301","full_name":"PolySync/oscc","owner":"PolySync","description":"Open Source Car Control 💻🚗🙌","archived":false,"fork":false,"pushed_at":"2019-12-10T18:04:57.000Z","size":47103,"stargazers_count":984,"open_issues_count":15,"forks_count":279,"subscribers_count":119,"default_branch":"master","last_synced_at":"2025-04-02T07:35:15.779Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PolySync.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-11-08T00:42:23.000Z","updated_at":"2025-03-29T10:08:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"9cd76b3d-af15-4774-8e34-321e187f0eae","html_url":"https://github.com/PolySync/oscc","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolySync%2Foscc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolySync%2Foscc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolySync%2Foscc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolySync%2Foscc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PolySync","download_url":"https://codeload.github.com/PolySync/oscc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253631985,"owners_count":21939370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T19:00:53.169Z","updated_at":"2025-05-11T20:31:18.452Z","avatar_url":"https://github.com/PolySync.png","language":"C++","readme":"\u003cimg src=\"https://raw.githubusercontent.com/wiki/PolySync/OSCC/images/oscc_logo_title.png\"\u003e\n\n\nOpen 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.\n\nOSCC 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 \u0026 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.\n\nAlthough 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.\n\nOur [Wiki](https://github.com/PolySync/OSCC/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.\n\n**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.**\n\n# Versions\n\nNew versions of the API and the firmware are released periodically as new features are added and bugs are\nfixed. **It is of vital importance that you update whenever there is a new version so that you can be certain\nyou are not using a version with known safety issues.**\n\nThere are four versions to be aware of:\n\n* **Sensor Interface Board (throttle and steering):** the version is printed on the front of the shield\n\n* **Vehicle Control Module (EV brakes):** the version is printed on the front of the shield\n\n* **Actuator Control Board (petrol brakes):** the version is printed on the front of the shield\n\n* **API and Firmware:** a single version is shared by both and listed in the [Releases section](https://github.com/PolySync/oscc/releases) of the repository.\n\nThe following table can be used to ensure that you use the appropriate firmware version with your boards:\n\n|                        | Board Version | Firmware Version |\n| ---------------------- | ------------- | ---------------- |\n| Sensor Interface       | \u003e= 1.0.0      | \u003e= 1.0.0         |\n| Vehicle Control        | 0.1.0         | \u003e= 1.1.0         |\n| Actuator Control       | \u003e= 1.2.0      | \u003e= 1.0.0         |\n|                        | \u003c 1.2.0 __*__ | \u003e= 1.0.1         |\n\n__*__ *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](#brake-startup-test) section.*\n\n# Repository Contents\n\n* **api** - Software API, so your program can seamlessly talk to our modules.\n* **firmware** - Arduino libraries and firmware for the OSCC modules.\n* **hardware** - PCB schematics and board designs for control modules.\n\n# Boards\n\nThe sensor interface and actuator control board schematics and design files are located in the\n`hardware/boards` directory.\n\nThanks to [Trey German](https://www.polymorphiclabs.com) for\nhelp designing the boards.\n\n# Building and Uploading Firmware\n\nThe OSCC Project is built around a number of individual firmware modules that inter-operate to allow communication with your vehicle.\nThese modules are built from Arduinos and Arduino shields designed specifically for interfacing with various vehicle components.\nOnce these modules have been installed in the vehicle and flashed with the firmware, the API can be used to\nreceive reports from the car and send spoofed commands.\n\n## Pre-requisites\n\nYou must have Arduino Core (version 1.8.5 or greater) and CMake (version 2.8 or greater) installed on\nyour machine.\n\n```\nsudo apt install build-essential cmake\n```\n\nA manual Arduino install is required since the debian package is older than 1.8.5\n```\nsudo apt-get purge arduino arduino-core\nwget http://arduino.cc/download.php?f=/arduino-1.8.5-linux64.tar.xz -O arduino-1.8.5.tar.xz\ntar -xf arduino-1.8.5.tar.xz\ncd arduino-1.8.5\nsudo mkdir -p /usr/share/arduino\nsudo cp -R * /usr/share/arduino\n```\n\nOSCC uses CMake to avoid some of the limitations of the Arduino IDE. Using this method you can build\nand upload the firmware from the command-line.\n\nCheck out [Arduino CMake](https://github.com/arduino-cmake/arduino-cmake) for more information.\n\n## Building the Firmware\n\nNavigate to the `firmware` directory and create a build directory inside of it:\n\n```\ncd firmware\nmkdir build\ncd build\n```\n\nTo generate Makefiles, tell `cmake` which vehicle to build for by supplying the\nappropriate build flag:\n\n| Vehicle         | Flag                   |\n| --------------- | ---------------------- |\n| Kia Soul Petrol | -DVEHICLE=kia_soul    |\n| Kia Soul EV     | -DVEHICLE=kia_soul_ev |\n| Kia Niro        | -DVEHICLE=kia_niro    |\n\n\nFor example, if you want to build firmware for the petrol Kia Soul:\n\n```\ncmake .. -DVEHICLE=kia_soul\n```\n\n**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.**\n\n```\ncmake .. -DVEHICLE=kia_soul -DSTEERING_OVERRIDE=OFF\n```\n\nIf 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.\n\n* 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.\n* Increasing this value will result in fewer false positives, but will make it more difficult to manually override the wheel.\n\nBy default, your firmware will have debug symbols which is good for debugging but increases\nthe size of the firmware significantly. To compile without debug symbols and optimizations\nenabled, use the following instead:\n\n```\ncmake .. -DVEHICLE=kia_soul -DCMAKE_BUILD_TYPE=Release\n```\n\n\u003ca name=\"brake-startup-test\"\u003e\u003c/a\u003e\n**NOTE:**\n\u003e For older (\u003c 1.2.0) versions of the actuator control board, you need to set an additional flag using `cmake .. -DKIA_SOUL=ON -DBRAKE_STARTUP_TEST=OFF` to disable startup tests that are not compatible with the previous board design.\n\nThis will generate the necessary files for building.\n\nNow you can build all of the firmware with `make`:\n\n```\nmake\n```\n\nIf you'd like to build only a specific module, you can provide a target name to\n`make` for whichever module you'd like to build:\n\n```\nmake brake\nmake can-gateway\nmake steering\nmake throttle\n```\n\n## Uploading the Firmware\n\nOnce the firmware is successfully built, you can upload it. When you connect to\nan Arduino with a USB cable, your machine assigns a serial device to it with the\npath `/dev/ttyACM#` where `#` is a digit starting at 0 and increasing by one with\neach additional Arduino connected.\n\nYou can upload firmware to a single module or to all modules. By default, `cmake`\nis configured to expect each module to be `/dev/ttyACM0`, so if you connect a\nsingle module to your machine, you can flash it without changing anything:\n\n```\nmake throttle-upload\n```\n\nHowever, if you want to flash all modules, you need to change the ports in\n`cmake` for each module to match what they are on your machine. The easiest way\nis to connect each module in alphabetical order (brake, CAN gateway, steering,\nthrottle) so that they are assigned `/dev/ttyACM0` through `/dev/ttyACM3` in\na known order. You can then change the ports during the `cmake ..` step:\n\n```\ncmake .. -DVEHICLE=kia_soul -DSERIAL_PORT_BRAKE=/dev/ttyACM0 -DSERIAL_PORT_CAN_GATEWAY=/dev/ttyACM1 -DSERIAL_PORT_STEERING=/dev/ttyACM2 -DSERIAL_PORT_THROTTLE=/dev/ttyACM3\n```\n\nThen you can flash all with one command:\n\n```\nmake all-upload\n```\n\nSometimes it takes a little while for the Arduino to initialize once connected, so if there is an\nerror thrown initially, wait a little bit and then retry the command.\n\n## Monitoring Arduino Modules\n\nIt is sometimes useful to monitor individual Arduino modules to check for proper operation and to\ndebug. If the modules have been built with the flag `-DCMAKE_BUILD_TYPE=Debug`, their debug\nprinting functionality will be enabled and they will print status information to the serial interface.\n\nThe GNU utility `screen` is one option to communicate with the Arduino via serial over USB. It can\nbe used to both receive the output of any `Serial.print` statements in your Arduino code, and to\npush commands over serial to the Arduino. If you don't already have it installed,\nyou can get it with the following command:\n\n```\nsudo apt install screen\n```\n\nYou need to enable debug mode with `-DDEBUG=ON` and tell `cmake` what serial port\nthe module you want to monitor is connected to\n(see [section on uploading](#uploading-the-firmware) for details on the default\nports for each module). The default baud rate is `115200` but you can change it:\n\n```\ncmake .. -DVEHICLE=kia_soul -DDEBUG=ON -DSERIAL_PORT_THROTTLE=/dev/ttyACM0 -DSERIAL_BAUD_THROTTLE=19200\n```\n\nYou can use a module's `monitor` target to automatically run `screen`, or a\nmodule's `monitor-log` target to run `screen` and output to a file called\n`screenlog.0` in the module's build directory:\n\n```\nmake brake-monitor\nmake brake-monitor-log\n```\n\nYou can exit `screen` with `C-a \\`.\n\nTo do more in-depth debugging you can use any of a number of serial monitoring applications.\nProcessing can be used quite effectively to provide output plots of data incoming across a serial\nconnection.\n\nBe aware that using serial printing can affect the timing of the firmware. You may experience\nstrange behavior while printing that does not occur otherwise.\n\n# Controlling Your Vehicle - an Example Application\n\nNow that all your Arduino modules are properly setup, it is time to start sending control commands.\n\nWe've created an example application, joystick commander, that uses the OSCC API to interface with the firmware, allowing you to send commands using a game controller and receive reports from the on-board OBD-II CAN. These commands are converted into CAN messages, which the OSCC API sends to the respective Arduino modules and are used to actuate the vehicle.\n\n[OSCC Joystick Commander](https://github.com/PolySync/oscc-joystick-commander)\n\nWe've also created a ROS node, that uses the OSCC API to interface with the firmware from ROS messages, allowing you to send commands and receive reports in ROS.\n\n[ROSCCO](https://github.com/PolySync/roscco)\n\n# OSCC API\n\n**Open and close CAN channel to OSCC Control CAN.**\n\n```c\noscc_result_t oscc_open( uint channel );\noscc_result_t oscc_close( uint channel );\n```\n\nThese methods are the start and end points of using the OSCC API in your application. ```oscc_open``` will open a socket connection\non the specified CAN channel, enabling it to quickly receive reports from and send commands to the firmware modules.\nWhen you are ready to terminate your application, ```oscc_close``` can terminate the connection.\n\n**NOTE:**\n\u003e 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\n\u003e to forward valid CAN messages to your application. If you have a section of code that is susceptible to conflicts with interrupts,\n\u003e you should temporarily block the SIGIO signal for the duration of that section and unblock it afterward.\n\n**Enable and disable all OSCC modules.**\n\n```c\noscc_result_t oscc_enable( void );\noscc_result_t oscc_disable( void );\n```\n\nAfter you have initialized your CAN connection to the firmware modules, these methods can be used to enable or disable the system. This\nallows your application to choose when to enable sending commands to the firmware. Although you can only send commands when the system is\nenabled, you can receive reports at any time.\n\n**Publish control command to the corresponding module.**\n\n```c\noscc_result_t publish_brake_position( double normalized_position );\noscc_result_t publish_steering_torque( double normalized_torque );\noscc_result_t publish_throttle_position( double normalized_position );\n```\n\nThese commands will forward a double value to the specified firmware module. The double values are [0.0, 1.0] for brake and throttle,\nand [-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\nas spoofed voltages to the vehicle to achieve the desired state. The API also contains safety checks to ensure no voltages outside of\nthe vehicle's expected range are sent.\n\n**NOTE:**\n\u003e Each of these functions must be called at least once every 200ms to prevent the modules from detecting a loss of communication to the\n\u003e controlling computer (at which point they would disable themselves).\n\n**Register callback function to handle OSCC report and OBD messages.**\n\n```c\noscc_result_t subscribe_to_brake_reports( void(*callback)(oscc_brake_report_s *report) );\noscc_result_t subscribe_to_steering_reports( void(*callback)(oscc_steering_report_s *report) );\noscc_result_t subscribe_to_throttle_reports( void(*callback)(oscc_throttle_report_s *report) );\noscc_result_t subscribe_to_fault_reports( void(*callback)(oscc_fault_report_s *report) );\noscc_result_t subscribe_to_obd_messages( void(*callback)(struct can_frame *frame) );\n```\n\nIn order to receive reports from the modules, your application will need to register a callback handler with the OSCC API.\nWhen the appropriate report for your callback function is received from the API's socket connection, it will then forward the\nreport to your software.\n\nEach module's reports are described in their respective wiki sections:\n\n* [Brake (EV)](https://github.com/PolySync/oscc/wiki/Firmware-Brake-%28EV%29#brake-report)\n* [Brake (Petrol)](https://github.com/PolySync/oscc/wiki/Firmware-Brake-%28Petrol%29#brake-report)\n* [Steering](https://github.com/PolySync/oscc/wiki/Firmware-Steering#steering-report)\n* [Throttle](https://github.com/PolySync/oscc/wiki/Firmware-Throttle#throttle-report)\n\nIn addition to OSCC specific reports, it will also forward any non-OSCC reports to any callback function registered with\n```subscribe_to_obd_messages```. This can be used to view CAN frames received from the vehicle's OBD-II CAN channel. If you know\nthe corresponding CAN frame's id, you can parse reports sent from the car.\n\n# Tests\n\nThere are two types of tests available: unit and property-based.\n\n## Test Dependencies\n\nThe unit tests and property-based tests each have their own set of dependencies\nrequired to run the tests.\n\nFor the unit tests you must have **Cucumber 2.0.0** and its dependency **Boost** installed:\n\n```\nsudo apt install ruby-dev libboost-dev\nsudo gem install cucumber -v 2.0.0\n```\n\nFor the property-based tests you must have **Rust**, its build manager **Cargo**, and **libclang**:\n\n```\nsudo apt install rustc cargo clang libclang-dev\n```\n\n## Running Tests\n\nBuilding and running the tests is similar to the firmware itself, but you must instead tell\n`cmake` to build the tests instead of the firmware with the `-DTESTS=ON` flag. We also pass\nthe `-DCMAKE_BUILD_TYPE=Release` flag so that `cmake` will disable debug symbols and enable\noptimizations, good things to do when running tests to ensure nothing breaks with\noptimizations. Lastly, you must tell the tests which vehicle header to use for\nthe tests (e.g., `-DVEHICLE=kia_soul`).\n\n```\ncd firmware\nmkdir build\ncd build\ncmake .. -DTESTS=ON -DCMAKE_BUILD_TYPE=Release -DVEHICLE=kia_soul\n```\n\n### Unit Tests\n\nEach module has a suite of unit tests that use **Cucumber** with **Cgreen**. There are pre-built\n64-bit Linux versions in `firmware/common/testing/framework`.\n\nBoost is required for Cucumber-CPP and has been statically linked into `libcucumber-cpp.a`.\nIf you need to build your own versions you can use the provided script `build_test_framework.sh`\nwhich will install the Boost dependencies (needed for building), clone the needed\nrepositories with specific hashes, build the Cgreen and Cucumber-CPP libraries,\nand place static Boost in the Cucumber-CPP library.\n\nThe built libraries will be placed in an `oscc_test_framework` directory in the\ndirectory that you ran the script from. You can then copy `oscc_test_framework/cucumber-cpp`\nand `oscc_test_framework/cgreen` to `firmware/common/testing/framework`.\n\nWe can run all of the unit tests available:\n\n```\nmake run-unit-tests\n```\n\nEach module's test can also be run individually:\n\n```\nmake run-brake-unit-tests\nmake run-can-gateway-unit-tests\nmake run-steering-unit-tests\nmake run-throttle-unit-tests\n```\n\nIf everything works correctly you should see something like this:\n\n```\n# language: en\nFeature: Receiving commands\n\n  Commands received from a controller should be processed and acted upon.\n\n  Scenario Outline: Enable throttle command sent from controller        # firmware/throttle/tests/features/receiving_commands.feature:8\n    Given throttle control is disabled                                  # firmware/throttle/tests/features/receiving_commands.feature:9\n    And the accelerator position sensors have a reading of \u003csensor_val\u003e # firmware/throttle/tests/features/receiving_commands.feature:10\n    When an enable throttle command is received                         # firmware/throttle/tests/features/receiving_commands.feature:12\n    Then control should be enabled                                      # firmware/throttle/tests/features/receiving_commands.feature:14\n    And the last command timestamp should be set                        # firmware/throttle/tests/features/receiving_commands.feature:15\n    And \u003cdac_a_val\u003e should be written to DAC A                          # firmware/throttle/tests/features/receiving_commands.feature:16\n    And \u003cdac_b_val\u003e should be written to DAC B                          # firmware/throttle/tests/features/receiving_commands.feature:17\n\n    Examples:\n      | sensor_val | dac_a_val | dac_b_val |\n      | 0          | 0         | 0         |\n      | 256        | 1024      | 1024      |\n      | 512        | 2048      | 2048      |\n      | 1024       | 4096      | 4096      |\n```\n\n### Property-Based Tests\n\nThe throttle, steering, and brake modules, along with the PID controller library, also contain a series of\nproperty-based tests.\n\nWe can run all of the property-based tests available:\n\n```\nmake run-property-tests\n```\n\nEach module's test can also be run individually:\n\n```\nmake run-brake-property-tests\nmake run-steering-property-tests\nmake run-throttle-property-tests\nmake run-pid-library-property-tests\n```\n\nOnce the tests have completed, the output should look similar to the following:\n\n```\nrunning 7 tests\ntest check_integral_term ... ok\ntest check_derivative_term ... ok\ntest check_proportional_term ... ok\ntest check_reversed_inputs ... ok\ntest check_same_control_for_same_inputs ... ok\ntest check_zeroize ... ok\n\ntest result: ok. 7 passed; 0 failed; 0 ignored; 0 measured\n\n   Doc-tests tests\n\nrunning 0 tests\n\ntest result: ok. 0 passed; 0 failed; 0 ignored; 0 measured\n```\n\n### All Tests\n\nFinally, as a convenience you can run all available tests:\n\n```\nmake run-all-tests\n```\n\n# Additional Vehicles \u0026 Contributing\n\nOSCC currently has information regarding the Kia Soul PS (2014-2018), but we want to grow! The\nrepository is structured to facilitate including more vehicles as more is learned about them.\n\nIn order to include information related to a new vehicle's specification, follow the format defined in ```api/include/vehicles/kia_soul.h``` and\nadd a `cmake` option to choose your new header when compiling the API.\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\n# License Information\n\nHardware source materials (e.g. schematics, board layouts, wiring diagrams, data sheets, physical\ninstallation documentation, 3D models, etc.) for the OSCC (Open Source Car Control) Project are\nlicensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).\n\nFirmware  and software source for the OSCC (Open Source Car Control) Project is licensed under the\nMIT License (MIT) unless otherwise noted (e.g. 3rd party dependencies, etc.).\n\nPlease see [LICENSE.md](LICENSE.md) for more details.\n\n\n# Contact Information\n\nPlease direct questions regarding OSCC and/or licensing to help@polysync.io.\n\n*Distributed as-is; no warranty is given.*\n\nCopyright (c) 2017 PolySync Technologies, Inc.  All Rights Reserved.\n","funding_links":[],"categories":["Miscellaneous","Kia","Podcasts and Episodes"],"sub_categories":["Episodes","Ford Transit"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPolySync%2FOSCC","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPolySync%2FOSCC","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPolySync%2FOSCC/lists"}