From 654e9efd04358febc1cbeb5229c744c4958b9680 Mon Sep 17 00:00:00 2001
From: Austin Morlan <amorlan@polysync.io>
Date: Thu, 9 Nov 2017 10:34:59 -0800
Subject: [PATCH 01/17] Update README with vehicle compatibility list

---
 README.md | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index bd658bf..e4b707a 100644
--- a/README.md
+++ b/README.md
@@ -49,16 +49,30 @@ This will clone into a directory called `oscc` where CMake will look for the OSC
 
 # Building Joystick Commander
 
-From the joystick commander directory, run the following sequence to build it:
+From the root directory, create a build directory inside of it:
 
 ```
 mkdir build
 cd build
+```
+
+To generate Makefiles, tell `cmake` which vehicle to build for by supplying the
+appropriate build flag:
+
+| Vehicle         | Flag             |
+| --------------- | ---------------- |
+| Kia Soul Petrol | -DKIA_SOUL=ON    |
+| Kia Soul EV     | -DKIA_SOUL_EV=ON |
+
+
+For example, if you want to build joystick commander for the petrol Kia Soul:
+
+```
 cmake .. -DKIA_SOUL=ON
 make
 ```
 
-The KIA_SOUL CMake option enables the API to swap between different vehicle specifications, allowing the firmware and API to remain car agnostic.
+The vehicle build flag enables the API to swap between different vehicle specifications, allowing the firmware and API to remain car agnostic.
 
 After initializing the CAN interface, use the channel number to start joystick commander and begin sending commands to the OSCC modules.
 

From 047933b10547bc566de9da944af2da94f3af8703 Mon Sep 17 00:00:00 2001
From: Austin Morlan <amorlan@polysync.io>
Date: Wed, 29 Nov 2017 12:02:56 -0800
Subject: [PATCH 02/17] Add deadzone for steering joystick

---
 src/commander.c | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/commander.c b/src/commander.c
index 15a0ca0..09885d0 100644
--- a/src/commander.c
+++ b/src/commander.c
@@ -191,21 +191,37 @@ static int get_normalized_position( unsigned long axis_index, double * const nor
 
     int axis_position = 0;
 
+    static const float deadzone = 0.3;
+
     return_code = joystick_get_axis( axis_index, &axis_position );
 
     if ( return_code == OSCC_OK )
     {
+        // this is between -1.0 and 1.0
+        double raw_normalized_position = ((double) axis_position / INT16_MAX);
+
         if ( axis_index == JOYSTICK_AXIS_STEER )
         {
-            ( *normalized_position ) = CONSTRAIN(
-            ((double) axis_position) / INT16_MAX,
-            -1.0,
-            1.0);
+            // if axis is in deadzone, do nothing
+            if ( fabs(raw_normalized_position) < deadzone)
+            {
+                ( *normalized_position ) = 0.0;
+            }
+            else
+            {
+                // normalize over non deadzone range
+                raw_normalized_position *= (fabs(raw_normalized_position) - deadzone) / (1.0 - deadzone);
+
+                ( *normalized_position ) = CONSTRAIN(
+                raw_normalized_position,
+                -1.0,
+                1.0);
+            }
         }
         else
         {
             ( *normalized_position ) = CONSTRAIN(
-            ((double) axis_position) / INT16_MAX,
+            raw_normalized_position,
             0.0,
             1.0);
         }

From f7d062c4ef8f801fb10c6374c795e17178870288 Mon Sep 17 00:00:00 2001
From: Austin Morlan <amorlan@polysync.io>
Date: Wed, 29 Nov 2017 12:41:38 -0800
Subject: [PATCH 03/17] Clear out exponential filter averages on disable

Prior to this commit, the exponential filter of the inputs
(triggers and joystick) were filtered so the modules received a smooth
series of commands, but the filters were not cleared after a disable,
causing the modules to actuate on old command values when re-enabling.
This commit clears the filters when control is not enabled.
---
 src/commander.c | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/src/commander.c b/src/commander.c
index 09885d0..a329ef5 100644
--- a/src/commander.c
+++ b/src/commander.c
@@ -166,8 +166,7 @@ int check_for_controller_update( )
             }
     }
 
-    if ( (return_code == OSCC_OK)
-        && (control_enabled == true) )
+    if ( return_code == OSCC_OK )
     {
         return_code = command_brakes( );
 
@@ -364,6 +363,12 @@ static int command_brakes( )
             return_code = oscc_publish_brake_position( average );
         }
     }
+    else
+    {
+        average = 0.0;
+
+        return_code = OSCC_OK;
+    }
 
     return ( return_code );
 }
@@ -408,6 +413,12 @@ static int command_throttle( )
             return_code = oscc_publish_throttle_position( average );
         }
     }
+    else
+    {
+        average = 0.0;
+
+        return_code = OSCC_OK;
+    }
 
     return ( return_code );
 }
@@ -439,9 +450,14 @@ static int command_steering( )
 
             return_code = oscc_publish_steering_torque( average );
         }
+    }
+    else
+    {
+        average = 0.0;
 
-
+        return_code = OSCC_OK;
     }
+
     return ( return_code );
 }
 

From 7ae3fd2f05cabe0d5111f67d6c90680844c8ffaf Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Thu, 7 Dec 2017 17:11:56 -0800
Subject: [PATCH 04/17] Update torque range to 20% of max range

Prior to this commit, steering range wasn't being limited from the application firmware whatsoever, i.e. it would iterate through the full allowable range of spoofs. This commit limits it to be 20% of the full range, allowing for better steering control and a better out-of-box user experience.
---
 src/commander.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/commander.c b/src/commander.c
index 15a0ca0..638671d 100644
--- a/src/commander.c
+++ b/src/commander.c
@@ -28,6 +28,7 @@
 #define JOYSTICK_AXIS_STEER (SDL_CONTROLLER_AXIS_LEFTX)
 #define JOYSTICK_BUTTON_ENABLE_CONTROLS (SDL_CONTROLLER_BUTTON_START)
 #define JOYSTICK_BUTTON_DISABLE_CONTROLS (SDL_CONTROLLER_BUTTON_BACK)
+#define STEERING_RANGE_PERCENTAGE (0.2)
 #define BRAKES_ENABLED_MIN (0.05)
 #define JOYSTICK_DELAY_INTERVAL (50000)
 #define COMMANDER_ENABLED ( 1 )
@@ -421,7 +422,8 @@ static int command_steering( )
 
             printf("Steering: %f\n", average);
 
-            return_code = oscc_publish_steering_torque( average );
+            // use only 30% of allowable range for controllability
+            return_code = oscc_publish_steering_torque( average * STEERING_RANGE_PERCENTAGE);
         }
 
 

From 75fd4fef277248baf75da92f4eb9a80fa4456a44 Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Thu, 7 Dec 2017 17:14:22 -0800
Subject: [PATCH 05/17] Fix typoo in documentation

---
 src/commander.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/commander.c b/src/commander.c
index 638671d..1ffee59 100644
--- a/src/commander.c
+++ b/src/commander.c
@@ -422,7 +422,7 @@ static int command_steering( )
 
             printf("Steering: %f\n", average);
 
-            // use only 30% of allowable range for controllability
+            // use only 20% of allowable range for controllability
             return_code = oscc_publish_steering_torque( average * STEERING_RANGE_PERCENTAGE);
         }
 

From da0fe099799c10811f0c90658a3c8202d223b698 Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Thu, 7 Dec 2017 17:15:51 -0800
Subject: [PATCH 06/17] Fix another typo

---
 src/commander.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/commander.c b/src/commander.c
index 1ffee59..11c8145 100644
--- a/src/commander.c
+++ b/src/commander.c
@@ -423,7 +423,7 @@ static int command_steering( )
             printf("Steering: %f\n", average);
 
             // use only 20% of allowable range for controllability
-            return_code = oscc_publish_steering_torque( average * STEERING_RANGE_PERCENTAGE);
+            return_code = oscc_publish_steering_torque( average * STEERING_RANGE_PERCENTAGE );
         }
 
 

From cd5bbf5c291ceb4b1271c5c7f3fc32f53fc233d5 Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Wed, 13 Dec 2017 18:20:57 -0800
Subject: [PATCH 07/17] Add Jenkinsfile

Prior to this commit, OSCC Joystick Commander didn't have any CI pipeline. This commit adds one.
---
 Jenkinsfile | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 Jenkinsfile

diff --git a/Jenkinsfile b/Jenkinsfile
new file mode 100644
index 0000000..70232fd
--- /dev/null
+++ b/Jenkinsfile
@@ -0,0 +1,20 @@
+
+#!groovy
+node('xenial') {
+  try {
+	stage('Checkout') {
+	  clean_checkout()
+	}
+    stage('Build') {
+        sh 'mkdir build && cd build && cmake .. -DKIA_SOUL=ON && make'
+      }
+      echo 'Build Complete!'
+    }
+  }
+  catch(Exception e) {
+    throw e;
+  }
+  finally {
+    deleteDir()
+  }
+}
\ No newline at end of file

From 21b5f0302d12b1a13e59058e43068fb5dfec8e87 Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Wed, 13 Dec 2017 18:22:16 -0800
Subject: [PATCH 08/17] Fix typo

---
 Jenkinsfile | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Jenkinsfile b/Jenkinsfile
index 70232fd..c3a16d2 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -1,4 +1,3 @@
-
 #!groovy
 node('xenial') {
   try {

From 90ecfbcc41b525007081ff4d2442cd177fce080e Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Wed, 13 Dec 2017 18:23:48 -0800
Subject: [PATCH 09/17] More carefully fix typoo because testing Jenkins
 locally is hard

---
 Jenkinsfile | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Jenkinsfile b/Jenkinsfile
index c3a16d2..d94430c 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -6,8 +6,7 @@ node('xenial') {
 	}
     stage('Build') {
         sh 'mkdir build && cd build && cmake .. -DKIA_SOUL=ON && make'
-      }
-      echo 'Build Complete!'
+        echo 'Build Complete!'
     }
   }
   catch(Exception e) {

From 83edf6a0a75a067c19b9ed9abd27772402139c99 Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Wed, 13 Dec 2017 18:26:05 -0800
Subject: [PATCH 10/17] Pull in OSCC repo for building

---
 Jenkinsfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Jenkinsfile b/Jenkinsfile
index d94430c..026e9eb 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -5,7 +5,7 @@ node('xenial') {
 	  clean_checkout()
 	}
     stage('Build') {
-        sh 'mkdir build && cd build && cmake .. -DKIA_SOUL=ON && make'
+        sh 'git clone git@github.com:PolySync/oscc.git --branch master && mkdir build && cd build && cmake .. -DKIA_SOUL=ON && make'
         echo 'Build Complete!'
     }
   }

From 2f1377c23e4788774c7be5cb6aec2fb7389dc990 Mon Sep 17 00:00:00 2001
From: Katie Cleary <kcleary@polysync.io>
Date: Tue, 2 Jan 2018 13:25:05 -0800
Subject: [PATCH 11/17] Remove unnecessary catch block

Prior to this commit, there was an unneeded catch block in the Jenkinsfile. This commit removes it.
---
 Jenkinsfile | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Jenkinsfile b/Jenkinsfile
index 026e9eb..b162528 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -9,9 +9,6 @@ node('xenial') {
         echo 'Build Complete!'
     }
   }
-  catch(Exception e) {
-    throw e;
-  }
   finally {
     deleteDir()
   }

From f7cca5b59f8b8a1f8845a9fda68065167ad09244 Mon Sep 17 00:00:00 2001
From: Shea Newton <snewton@polysync.io>
Date: Tue, 16 Jan 2018 09:59:29 -0800
Subject: [PATCH 12/17] Make initialization of `joystick_data` explicit

Prior to this commit the initialization of the static global variable `joystick_data` was initialized ambiguously and what looked like erroneously.

This commit represents a revision explicit initialization instead.

Motivation for this change was a support ticket raised with an email to `help@polysync.io`

Note to reviewers: I validated that after this change the joystick commander still behaved as _I_ expected on the car but would HIGHLY recommened that reviewers do the same.

Thanks!
---
 src/joystick.c | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/joystick.c b/src/joystick.c
index 9dc59ed..b786739 100644
--- a/src/joystick.c
+++ b/src/joystick.c
@@ -62,7 +62,12 @@ typedef struct
 
 
 static joystick_guid_s joystick_guid;
-static joystick_device_data_s joystick_data = { NULL, &joystick_guid };
+static joystick_device_data_s joystick_data = {
+    .controller = NULL,
+    .haptic = NULL,
+    .guid = &joystick_guid
+    };
+
 static joystick_device_data_s* joystick = NULL;
 
 static int joystick_init_subsystem( )
@@ -171,7 +176,7 @@ int joystick_open( unsigned long device_index )
 
     if ( joystick != NULL )
     {
-        joystick->controller = 
+        joystick->controller =
             (void*) SDL_GameControllerOpen( (int) device_index );
 
         if ( joystick->controller == JOYSTICK_DEVICE_CONTROLLER_INVALID )
@@ -183,7 +188,7 @@ int joystick_open( unsigned long device_index )
             ret = OSCC_OK;
 
             const SDL_JoystickGUID m_guid =
-                SDL_JoystickGetGUID( 
+                SDL_JoystickGetGUID(
                     SDL_GameControllerGetJoystick( joystick->controller ) );
 
             memcpy( joystick_guid.data, m_guid.data, sizeof( m_guid.data ) );
@@ -196,10 +201,10 @@ int joystick_open( unsigned long device_index )
                                        joystick_guid.ascii_string,
                                        sizeof( joystick_guid.ascii_string ) );
 
-            joystick->haptic = 
-                (void*) SDL_HapticOpenFromJoystick( 
+            joystick->haptic =
+                (void*) SDL_HapticOpenFromJoystick(
                     SDL_GameControllerGetJoystick( joystick->controller ));
- 
+
             if ( SDL_HapticRumbleInit( joystick->haptic ) != 0 )
             {
                 SDL_HapticClose( joystick->haptic );
@@ -217,7 +222,7 @@ void joystick_close( )
         {
             if ( SDL_GameControllerGetAttached( joystick->controller ) ==            SDL_TRUE )
             {
-                if ( joystick->haptic ) 
+                if ( joystick->haptic )
                 {
                     SDL_HapticClose( joystick->haptic );
                 }
@@ -266,7 +271,7 @@ int joystick_get_axis( unsigned long axis_index, int * const position )
         const Sint16 pos = SDL_GameControllerGetAxis( joystick->controller,
                                                       axis_index );
 
-        
+
         ( *position ) = (int) pos;
     }
 
@@ -288,12 +293,12 @@ int joystick_get_button( unsigned long button_index,
         if ( m_state == 1 )
         {
             ( *button_state ) = JOYSTICK_BUTTON_STATE_PRESSED;
-            
+
             if ( joystick->haptic )
             {
                 SDL_HapticRumblePlay( joystick->haptic, 1.0f, 100 );
             }
-            
+
             ( void ) usleep( BUTTON_PRESSED_DELAY );
         }
         else

From 94103378db18919ef9b90218a78f50a28ed5bfa0 Mon Sep 17 00:00:00 2001
From: Robert Brown <rbrown@polysync.io>
Date: Wed, 6 Jun 2018 17:27:53 -0700
Subject: [PATCH 13/17] Add OSCC configuration file

Prior to this commit joystick commander required an ifdef block to support
different platforms. This commit updates joystick commander so that the oscc
configuration can be referenced instead keeping platform support in the oscc repo.
---
 CMakeLists.txt | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index fec70ec..75e988d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -5,11 +5,7 @@ project(oscc-joystick-commander)
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(SDL2 REQUIRED sdl2)
 
-if(KIA_SOUL)
-    add_definitions(-DKIA_SOUL)
-elseif(KIA_SOUL_EV)
-    add_definitions(-DKIA_SOUL_EV)
-endif()
+include(oscc/api/OsccConfig.cmake)
 
 add_executable(
     oscc-joystick-commander
@@ -29,4 +25,3 @@ target_link_libraries(
     oscc-joystick-commander
     PRIVATE
     ${SDL2_LIBRARIES})
-

From 0b2269a190cf8dc5c8596a973883431fb657e0da Mon Sep 17 00:00:00 2001
From: Robert Brown <rbrown@polysync.io>
Date: Wed, 6 Jun 2018 17:36:58 -0700
Subject: [PATCH 14/17] Add OSCC submodule

Prior to this commit joystick commander required the user to clone oscc into
the joystick commander directory and did not keep track of oscc versions. This
commit fxes that by adding oscc as a submodule so that updates to oscc api and
joystick commander can be kept in lockstep.
---
 .gitmodules | 3 +++
 README.md   | 2 +-
 oscc        | 1 +
 3 files changed, 5 insertions(+), 1 deletion(-)
 create mode 100644 .gitmodules
 create mode 160000 oscc

diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 0000000..34cc7a8
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "oscc"]
+	path = oscc
+	url = https://github.com/PolySync/oscc.git
diff --git a/README.md b/README.md
index e4b707a..5652710 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ cd oscc-joystick-commander
 From within the joystick commander directory, clone the OSCC repo:
 
 ```
-git clone git@github.com:PolySync/oscc.git --branch master
+git submodule update --init
 ```
 
 This will clone into a directory called `oscc` where CMake will look for the OSCC API when it builds joystick commander.
diff --git a/oscc b/oscc
new file mode 160000
index 0000000..2a2f112
--- /dev/null
+++ b/oscc
@@ -0,0 +1 @@
+Subproject commit 2a2f1122e620dfe0767206a2ea81ea8a7ca42552

From 3454aa3c72e4b02f5f0c2e9008dc2086c6921dd7 Mon Sep 17 00:00:00 2001
From: Chris Otos <cotos@polysync.io>
Date: Tue, 9 Jul 2019 13:32:30 -0700
Subject: [PATCH 15/17] update oscc to v1.2.4, add validation modifictions

Before this PR the oscc module was v1.2.3

This PR will make the following changes.

oscc default module is now:  v1.2.4

Changed the steering range percentage to the value used for validation.

`#define STEERING_RANGE_PERCENTAGE (0.36)`

Changed commander updat interval so JC will work with the safety gateway

`#define COMMANDER_UPDATE_INTERVAL_MICRO (5000)`
---
 oscc            | 2 +-
 src/commander.c | 2 +-
 src/main.c      | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/oscc b/oscc
index 2a2f112..45ce9fc 160000
--- a/oscc
+++ b/oscc
@@ -1 +1 @@
-Subproject commit 2a2f1122e620dfe0767206a2ea81ea8a7ca42552
+Subproject commit 45ce9fccda8b75e58612b70bd45d88bc0621126b
diff --git a/src/commander.c b/src/commander.c
index ca6dea1..fa3cb2d 100644
--- a/src/commander.c
+++ b/src/commander.c
@@ -28,7 +28,7 @@
 #define JOYSTICK_AXIS_STEER (SDL_CONTROLLER_AXIS_LEFTX)
 #define JOYSTICK_BUTTON_ENABLE_CONTROLS (SDL_CONTROLLER_BUTTON_START)
 #define JOYSTICK_BUTTON_DISABLE_CONTROLS (SDL_CONTROLLER_BUTTON_BACK)
-#define STEERING_RANGE_PERCENTAGE (0.2)
+#define STEERING_RANGE_PERCENTAGE (0.36)
 #define BRAKES_ENABLED_MIN (0.05)
 #define JOYSTICK_DELAY_INTERVAL (50000)
 #define COMMANDER_ENABLED ( 1 )
diff --git a/src/main.c b/src/main.c
index 292de37..9bf057e 100644
--- a/src/main.c
+++ b/src/main.c
@@ -10,7 +10,7 @@
 #include "commander.h"
 #include "can_protocols/steering_can_protocol.h"
 
-#define COMMANDER_UPDATE_INTERVAL_MICRO (50000)
+#define COMMANDER_UPDATE_INTERVAL_MICRO (5000)
 #define SLEEP_TICK_INTERVAL_MICRO (1000)
 
 static int error_thrown = OSCC_OK;

From 45bc4c6b7371d7e2832d2197897951a9da668143 Mon Sep 17 00:00:00 2001
From: cotos <cotos@polysync.io>
Date: Tue, 9 Jul 2019 17:19:25 -0700
Subject: [PATCH 16/17] Updated README and LICENSE files

I updated the README to follow the the DriveKit README on the
`feature/dfu-bootloader` branch.

I updated the MIT copyright to 2019 in the license and readme files.
---
 LICENSE.md |  2 +-
 README.md  | 96 ++++++++++++++++++++++++++++--------------------------
 2 files changed, 51 insertions(+), 47 deletions(-)

diff --git a/LICENSE.md b/LICENSE.md
index b9f7a8d..2fad33b 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 PolySync Technologies
+Copyright (c) 2019 PolySync Technologies
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 5652710..28f6357 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 <img src="https://raw.githubusercontent.com/wiki/PolySync/OSCC/images/oscc_logo_title.png">
 
+# Joystick Commander
+
+## Overview
+
 Joystick commander is an example application designed to show how the Open Source Car Control API can be used to recieve reports from and send commands to a drive by-wire enabled vehicle.
 
 Using an SDL2 supported game controller, inputs are normalized and converted to relative torque, throttle, and brake commands. This application also demonstrates registering callback functions to recieve and parse OSCC reports as well as vehicle state reports from the car's OBD-II CAN network.
@@ -7,7 +11,9 @@ Using an SDL2 supported game controller, inputs are normalized and converted to
 For more information about OSCC, check out our [github](https://github.com/PolySync/oscc).
 
 
-# Pre-requisites:
+## Getting Started
+
+These instructions have been tested with a new Ubuntu 18.04 installation.
 
 - OSCC's API and firmware modules are both required, and the modules must be installed on the vehicle
 - The socketcan driver for USB and PCIe CAN interfaces is required, and is pre-installed on most Linux systems
@@ -20,104 +26,102 @@ This application has been tested with a Logitech F310 gamepad and a wired Xbox 3
 
 [Logitech Gamepad F310](http://a.co/3GoUlkN)
 
-Install the SDL2 library with the command below.
 
-```
-sudo apt install libsdl2-dev
+### 1. Install Dependencies
+
+You will need several packages installed on your machine in order to build the oscc-joystick-commander application. Use the following command to install them using `apt`:
+
+```sh
+sudo apt install git cmake libsdl2-dev
 ```
 
+### 2. Set up this repository locally
 
-# Getting OSCC & Joystick Commander
+Clone this repository to your machine, if you have not already done so:
 
-If you haven't already, install the OSCC hardware modules onto the target vehicle.
+```sh
+# clone the repository
+$ git clone git@github.com:PolySync/oscc-joystick-commander.git
 
-Once the hardware is installed and the firmware is flashed, clone and enter the joystick commander repo:
 
-```
-git clone git@github.com:PolySync/oscc-joystick-commander.git
-cd oscc-joystick-commander
+# change the current directory to the repository
+$ cd oscc-joystick-commander
 ```
 
-From within the joystick commander directory, clone the OSCC repo:
+Note: If you do not have a github account you will need to clone the repository using HTTPS.
 
-```
-git submodule update --init
-```
+Then, from within that directory, sync and initialize Git submodules:
 
-This will clone into a directory called `oscc` where CMake will look for the OSCC API when it builds joystick commander.
+```sh
+$ git submodule sync
+$ git submodule update --init --recursive
+```
 
+## Building Joystick Commander
 
-# Building Joystick Commander
+### 1. CMake Configuration
 
-From the root directory, create a build directory inside of it:
+Before you can build the oscc-joystick-commander application, you must use cmake to configure the project. From within the oscc-joystick-commander repository on your machine:
 
+```sh
+# create a build directory that will act as our workspace, and cd to it
+$ mkdir build/
+$ cd build/
 ```
-mkdir build
-cd build
-```
-
-To generate Makefiles, tell `cmake` which vehicle to build for by supplying the
-appropriate build flag:
 
-| Vehicle         | Flag             |
-| --------------- | ---------------- |
-| Kia Soul Petrol | -DKIA_SOUL=ON    |
-| Kia Soul EV     | -DKIA_SOUL_EV=ON |
+From there, you will run `cmake` to build a platform-specific Makefile. `cmake` will require some arguments, including the vehicle that the firmware is being built for. You can get a list of supported vehicles using the following command:
 
+```sh
+$ cmake -LA .. 2>/dev/null | grep 'VEHICLE_VALUES'
+```
 
-For example, if you want to build joystick commander for the petrol Kia Soul:
+For example, to configure `cmake` to build a platform-specific Makefile for the Kia Niro, you would use the following command (from within the `build/` directory you created):
 
+```sh
+$ cmake -DVEHICLE=kia_niro ..
 ```
-cmake .. -DKIA_SOUL=ON
-make
-```
 
-The vehicle build flag enables the API to swap between different vehicle specifications, allowing the firmware and API to remain car agnostic.
+
+### CAN interface
 
 After initializing the CAN interface, use the channel number to start joystick commander and begin sending commands to the OSCC modules.
 
 For example with a Kvaser Leaf Light attached, using a bitrate of 500000 and a CAN channel of 0:
 
-```
+```sh
  sudo ip link set can0 type can bitrate 500000
  sudo ip link set up can0
 ```
 
 You would then run:
 
-```
+```sh
 ./oscc-joystick-commander 0
 ```
 
 For more information on setting up a socketcan interface, check out [this guide](http://elinux.org/Bringing_CAN_interface_up).
 
+# Application Details
 
-# Controlling the Vehicle with the Joystick Gamepad
+## Controlling the Vehicle with the Joystick Gamepad
 
-Once the joystick commander is up and running you can use it to send commands to the Arduino modules.
+Once the joystick commander is up and running you can use it to send commands to DriveKit.
 Use the left trigger to brake, the right trigger for throttle, and the left gamepad axis to control steering.
 
 The vehicle will only respond to commands if control is enabled with the start button. The back button disables control.
 
-
-# Application Details
-
-
 ### main
 
-Entry point of joystick commander. Initializes OSCC interface, checks for controller updates in 50 ms intervals, and closes the interface when the program terminates. This contains the applications main loop.
-
+`main.c` is the entry point of joystick commander. Initializes OSCC interface, checks for controller updates in 5 ms intervals, and closes the interface when the program terminates. This contains the applications main loop.
 
 ### joystick
 
 `joystick.c` contains the functionality necessary to initialize and interact with the game controller.
 
-
 ### commander
 
 The commander files contain the joystick commander's interactivity with the OSCC API. It demonstrates opening and closing the CAN channel communications with OSCC's control CAN network, sending enable/disable commands to the modules through the API, retrieving OSCC reports through callback functions, and sending commands through the OSCC `publish` functions.
 
-
 # Using OSCC API
 
 To use the OSCC API in your applications, you need to include any relevant header files.
@@ -125,7 +129,7 @@ To use the OSCC API in your applications, you need to include any relevant heade
 * The can message protocols are located in `oscc/api/include/can_protocols/`
     * These specify the structs we use for steering, throttle, brake, and fault reports
 * Vehicle specific macros and values are located in `oscc/api/include/vehicles/`
-	* You only need to include `vehicles.h`, which will include the relevant vehicle-specific header depending on the option provided to CMake (e.g., `-DKIA_SOUL=ON` will include `kia_soul.h`)
+	* You only need to include `vehicles.h`, which will include the relevant vehicle-specific header depending on the option provided to CMake (e.g., `-DVEHICLE=kia_niro` will include `kia_niro.h`)
 * `oscc/api/include/oscc.h` includes the functionality to interface with the OSCC API
 
 
@@ -144,4 +148,4 @@ Please direct questions regarding OSCC and/or licensing to help@polysync.io.
 
 *Distributed as-is; no warranty is given.*
 
-Copyright (c) 2017 PolySync Technologies, Inc.  All Rights Reserved.
+Copyright (c) 2019 PolySync Technologies, Inc.  All Rights Reserved.

From 2a60f8f908a4f2260016a6abbdc94f7a1c0fac40 Mon Sep 17 00:00:00 2001
From: cotos <cotos@polysync.io>
Date: Wed, 10 Jul 2019 10:05:57 -0700
Subject: [PATCH 17/17] Update README.md

Added note for debug flag
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 28f6357..4377f9d 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,7 @@ For example, to configure `cmake` to build a platform-specific Makefile for the
 $ cmake -DVEHICLE=kia_niro ..
 ```
 
+Note: You may also choose to add the flag -DDEBUG=ON to enable debug messaging, serial console, etc. This should not be used for production builds.
 
 ### CAN interface