From 2c80efc4b23839b73dc3f0398b8895bdb34004ef Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:12:56 -0500 Subject: [PATCH 01/21] Add VSCode information to the README --- Firmware/README.md | 56 ++++++++++----------------------- Firmware/configuring-eclipse.md | 35 +++++++++++++++++++++ Firmware/configuring-vscode.md | 24 ++++++++++++++ 3 files changed, 75 insertions(+), 40 deletions(-) create mode 100644 Firmware/configuring-eclipse.md create mode 100644 Firmware/configuring-vscode.md diff --git a/Firmware/README.md b/Firmware/README.md index af5fac44..a27253f5 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -87,8 +87,11 @@ An upcoming feature will enable automatic tuning. Until then, here is a rough tu By default both motors are enabled, and the default control mode is position control. If you want a different mode, you can change `.control_mode`. To disable a motor, set `.enable_control` and `.do_calibration` to false. +---- ## Compiling and downloading firmware + + ### Getting a programmer Get a programmer that supports SWD (Serial Wire Debugging) and is ST-link v2 compatible. You can get them really cheap on [eBay](http://www.ebay.co.uk/itm/ST-Link-V2-Emulator-Downloader-Programming-Mini-Unit-STM8-STM32-with-20CM-Line-/391173940927?hash=item5b13c8a6bf:g:3g8AAOSw~OdVf-Tu) or many other places. @@ -117,23 +120,32 @@ Install the following: After installing all of the above, open a Git Bash shell. Continue at section [Building the firmware](#building-the-firmware). +### IDE +ODrive is a Makefile project. It does not require an IDE, but the open-source VSCode is recommended. See [Configuring VSCode](configuring-vscode.md) for information on how to do this. + ### Building the firmware * Make sure you have cloned the repository. -* Navigate your terminal (bash/cygwin) to the ODrive/Firmware dir. -* Run `make` in the root of this repository. +* VSCode: + * Tasks -> Run Build Task +* Terminal: + * Navigate your terminal (bash/cygwin) to the ODrive/Firmware dir. + * Run `make` in the root of this repository. ### Flashing the firmware * **Make sure you have [configured the parameters first](#configuring-parameters)** * Connect `SWD`, `SWC`, and `GND` on connector J2 to the programmer. * You need to power the board by only **ONE** of the following: VCC(3.3v), 5V, or the main power connection (the DC bus). The USB port (J1) does not power the board. -* Run `make flash` in the root of this repository. +* VSCode: + * Tasks -> Run Task -> flash +* Terminal: + * Run `make flash` in the root of this repository. If the flashing worked, you can start sending commands. If you want to do that now, you can go to [Communicating over USB or UART](#communicating-over-usb-or-uart). ### Debugging the firmware The following options are known to work and supported: * Command line GDB. Run `make gdb`. This will reset and halt at program start. Now you can set breakpoints and run the program. If you know how to use gdb, you are good to go. -* Eclipse, see [Setting up Eclipse development environment](#setting-up-eclipse-development-environment). +* Eclipse, see [Setting up Eclipse development environment](configuring-eclipse.md). * Visual Studio Code. The solution we have is not the most elegant, and if you know a better way, please do help us. * Make sure you have the Firmware folder as your active folder * Flash the board with the newest code (starting debug session doesn't do this) @@ -189,42 +201,6 @@ You will likely want the pinout for this process. It is available [here](https:/ * Press `Project -> Generate code` * You may need to let it download some drivers and such. -## Setting up Eclipse development environment - -### Install -* Install [Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neon3) -* Install the [OpenOCD Eclipse plugin](http://gnuarmeclipse.github.io/plugins/install/) - -### Import project -* File -> Import -> C/C++ -> Existing Code as Makefile Project -* Browse for existing code location, find the OdriveFirmware root. -* In the Toolchain options, select `Cross GCC` -* Hit Finish -* Build the project (press ctrl-B) - -![Toolchain options](screenshots/CodeAsMakefile.png "Toolchain options") - -### Load the launch configuration -* File -> Import -> Run/Debug -> Launch Configurations -> Next -* Highlight (don't tick) the OdriveFirmare folder in the left column -* Tick OdriveFirmware.launch in the right column -* Hit Finish - -![Launch Configurations](screenshots/ImportLaunch.png "Launch Configurations") - -### Launch! -* Make sure the programmer is connected to the board as per [Flashing the firmware](#flashing-the-firmware). -* Press the down-arrow of the debug symbol in the toolbar, and hit Debug Configurations - * You can also hit Run -> Debug Configurations -* Highlight the debug configuration you imported, called OdriveFirmware. If you do not see the imported launch configuration rename your project to `ODriveFirmware` or edit the launch configuration to match your project name by unfiltering unavailable projects: - -![Launch Configuration Filters](screenshots/LaunchConfigFilter.png "Launch Configuration Filters") - -* Hit Debug -* Eclipse should flash the board for you and the program should start halted on the first instruction in `Main` -* Set beakpoints, step, hit Resume, etc. -* Make some cool features! ;D - ## Notes for Contributors In general the project uses the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html), except that the default indendtation is 4 spaces, and that the 80 character limit is not very strictly enforced, merely encouraged. diff --git a/Firmware/configuring-eclipse.md b/Firmware/configuring-eclipse.md new file mode 100644 index 00000000..25da57e2 --- /dev/null +++ b/Firmware/configuring-eclipse.md @@ -0,0 +1,35 @@ +## Setting up Eclipse development environment + +### Install +* Install [Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neon3) +* Install the [OpenOCD Eclipse plugin](http://gnuarmeclipse.github.io/plugins/install/) + +### Import project +* File -> Import -> C/C++ -> Existing Code as Makefile Project +* Browse for existing code location, find the OdriveFirmware root. +* In the Toolchain options, select `Cross GCC` +* Hit Finish +* Build the project (press ctrl-B) + +![Toolchain options](screenshots/CodeAsMakefile.png "Toolchain options") + +### Load the launch configuration +* File -> Import -> Run/Debug -> Launch Configurations -> Next +* Highlight (don't tick) the OdriveFirmare folder in the left column +* Tick OdriveFirmware.launch in the right column +* Hit Finish + +![Launch Configurations](screenshots/ImportLaunch.png "Launch Configurations") + +### Launch! +* Make sure the programmer is connected to the board as per [Flashing the firmware](#flashing-the-firmware). +* Press the down-arrow of the debug symbol in the toolbar, and hit Debug Configurations + * You can also hit Run -> Debug Configurations +* Highlight the debug configuration you imported, called OdriveFirmware. If you do not see the imported launch configuration rename your project to `ODriveFirmware` or edit the launch configuration to match your project name by unfiltering unavailable projects: + +![Launch Configuration Filters](screenshots/LaunchConfigFilter.png "Launch Configuration Filters") + +* Hit Debug +* Eclipse should flash the board for you and the program should start halted on the first instruction in `Main` +* Set beakpoints, step, hit Resume, etc. +* Make some cool features! ;D \ No newline at end of file diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md new file mode 100644 index 00000000..5f09055f --- /dev/null +++ b/Firmware/configuring-vscode.md @@ -0,0 +1,24 @@ +# Configuring VSCode + +VSCode is the recommended IDE for working with the ODrive codebase. It is a light-weight text editor with Git integration and GDB debugging functionality. + +Before doing the VSCode setup, make sure you've installed all of your [prerequisites](README.md#installing-prerequisites) + +--- +## Setup Procedure +1. Clone the ODrive repository +1. [Download VSCode](https://code.visualstudio.com/download) +1. Install extensions. This can be done directly from VSCode (Ctrl+Shift+X) + * Required extensions: + * C/C++ + * Native Debug + * Recommended Extensions: + * vscode-icons + * Code Outline + * Include Autocomplete + * Path Autocomplete + * Auto Comment Blocks +1. Restart VSCode +1. Open the VSCode Workspace file, which is located in the root of the ODrive repository. It is called `VSCodeWorkspace.code-workspace`. The first time you open it, VSCode will install some dependencies. If it fails, you may need to [change your proxy settings](https://code.visualstudio.com/docs/getstarted/settings). + +You should now be ready to compile and test the ODrive project. See [Building the Firmware](README.md#building-the-firmware) \ No newline at end of file From f7dd9392f31ea79234060b85838fea94f48e2487 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:13:21 -0500 Subject: [PATCH 02/21] Formatting --- Firmware/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/Firmware/README.md b/Firmware/README.md index a27253f5..95d7369c 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -89,9 +89,6 @@ If you want a different mode, you can change `.control_mode`. To disable a motor ---- ## Compiling and downloading firmware - - - ### Getting a programmer Get a programmer that supports SWD (Serial Wire Debugging) and is ST-link v2 compatible. You can get them really cheap on [eBay](http://www.ebay.co.uk/itm/ST-Link-V2-Emulator-Downloader-Programming-Mini-Unit-STM8-STM32-with-20CM-Line-/391173940927?hash=item5b13c8a6bf:g:3g8AAOSw~OdVf-Tu) or many other places. From cc0569ee4cc3f7a9d07f8372b1718d750d9fc858 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:29:10 -0500 Subject: [PATCH 03/21] Move the IDE instructions to other files --- Firmware/README.md | 41 +++++++++++++--------------------- Firmware/configuring-vscode.md | 29 +++++++++++++++++++++++- 2 files changed, 43 insertions(+), 27 deletions(-) diff --git a/Firmware/README.md b/Firmware/README.md index 95d7369c..e1b60ef9 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -12,7 +12,7 @@ If you are a developer, you are encouraged to use the `devel` branch, as it cont - [Compiling and downloading firmware](#compiling-and-downloading-firmware) - [Communicating over USB or UART](#communicating-over-usb-or-uart) - [Generating startup code](#generating-startup-code) -- [Setting up Eclipse development environment](#setting-up-eclipse-development-environment) +- [Setting up an IDE](#setting-up-an-IDE) - [Notes for Contributors](#notes-for-contributors) @@ -115,46 +115,35 @@ Install the following: * [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm). Make is used to script the compilation process. Download and run the complete package setup program. Add the path of the binaries to your PATH environment variable. For me this was at `C:\Program Files (x86)\GnuWin32\bin`. For details on how to set your path envirment in windows see [these instructions.](https://www.java.com/en/download/help/path.xml) * OpenOCD. Follow the instructions at [GNU ARM Eclipse - How to install the OpenOCD binaries](http://gnuarmeclipse.github.io/openocd/install/), including the part about ST-LINK/V2 drivers. Add the path of the binaries to your PATH environment variable. For me this was at `C:\Program Files\GNU ARM Eclipse\OpenOCD\0.10.0-201704182147-dev\bin`. -After installing all of the above, open a Git Bash shell. Continue at section [Building the firmware](#building-the-firmware). +--- +## Setting up an IDE +ODrive is a Makefile project. It does not require an IDE, but the open-source VSCode is recommended. It is also possible to use Eclipse. If you'd like to go that route, please see the respective configuration document: -### IDE -ODrive is a Makefile project. It does not require an IDE, but the open-source VSCode is recommended. See [Configuring VSCode](configuring-vscode.md) for information on how to do this. +* [Configuring VSCode](configuring-vscode.md) +* [Configuring Eclipse](configuring-eclipse.md) + +--- +## No IDE Instructions +After installing all of the above, open a Git Bash shell. Continue at section [Building the firmware](#building-the-firmware). ### Building the firmware * Make sure you have cloned the repository. -* VSCode: - * Tasks -> Run Build Task -* Terminal: - * Navigate your terminal (bash/cygwin) to the ODrive/Firmware dir. - * Run `make` in the root of this repository. +* Navigate your terminal (bash/cygwin) to the ODrive/Firmware dir. +* Run `make` in the root of this repository. ### Flashing the firmware * **Make sure you have [configured the parameters first](#configuring-parameters)** * Connect `SWD`, `SWC`, and `GND` on connector J2 to the programmer. * You need to power the board by only **ONE** of the following: VCC(3.3v), 5V, or the main power connection (the DC bus). The USB port (J1) does not power the board. -* VSCode: - * Tasks -> Run Task -> flash -* Terminal: - * Run `make flash` in the root of this repository. +* Run `make flash` in the root of this repository. If the flashing worked, you can start sending commands. If you want to do that now, you can go to [Communicating over USB or UART](#communicating-over-usb-or-uart). ### Debugging the firmware -The following options are known to work and supported: -* Command line GDB. Run `make gdb`. This will reset and halt at program start. Now you can set breakpoints and run the program. If you know how to use gdb, you are good to go. -* Eclipse, see [Setting up Eclipse development environment](configuring-eclipse.md). -* Visual Studio Code. The solution we have is not the most elegant, and if you know a better way, please do help us. - * Make sure you have the Firmware folder as your active folder - * Flash the board with the newest code (starting debug session doesn't do this) - * Tasks -> Run Task -> openocd - * Debug -> Start Debugging - * The processor will reset and halt. - * Set your breakpoints. Note: you can only set breakpoints when the processor is halted, if you set them during run mode, they won't get applied. - * Run - * When you are done, you must kill the openocd task before you are able to flash the board again: Tasks -> Terminate task -> openocd. +* Run `make gdb`. This will reset and halt at program start. Now you can set breakpoints and run the program. If you know how to use gdb, you are good to go. +--- ## Communicating over USB or UART - ### From Linux/Windows/macOS There are two simple python scripts to help you get started with controlling the ODrive using python. diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index 5f09055f..5b5abf4a 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -21,4 +21,31 @@ Before doing the VSCode setup, make sure you've installed all of your [prerequis 1. Restart VSCode 1. Open the VSCode Workspace file, which is located in the root of the ODrive repository. It is called `VSCodeWorkspace.code-workspace`. The first time you open it, VSCode will install some dependencies. If it fails, you may need to [change your proxy settings](https://code.visualstudio.com/docs/getstarted/settings). -You should now be ready to compile and test the ODrive project. See [Building the Firmware](README.md#building-the-firmware) \ No newline at end of file +You should now be ready to compile and test the ODrive project. + +## Building the Firmware +* Tasks -> Run Build Task + +A terminal window will open with your native shell. VSCode is configured to run the command `make -j4` in this terminal. + +## Flashing the Firmware +* Tasks -> Run Task -> flash + +A terminal window will open with your native shell. VSCode is configured to run the command `make flash` in this terminal. + +If the flashing worked, you can start sending commands. If you want to do that now, you can go to [Communicating over USB or UART](README.md#communicating-over-usb-or-uart). + +## Debugging +The solution we have is not the most elegant, and if you know a better way, please do help us. + * Make sure you have the Firmware folder as your active folder + * Flash the board with the newest code (starting debug session doesn't do this) + * Tasks -> Run Task -> openocd + * Debug -> Start Debugging + * The processor will reset and halt. + * Set your breakpoints. Note: you can only set breakpoints when the processor is halted, if you set them during run mode, they won't get applied. + * Run + * When you are done, you must kill the openocd task before you are able to flash the board again: Tasks -> Terminate task -> openocd. + +## Cleaning the Build +This sometimes needs to be done if you change branches. +* Open a terminal (View -> Integrated Terminal) and enter `make clean` \ No newline at end of file From 91cee4a4b258e4298c95527853add7d2e6897e0a Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:31:59 -0500 Subject: [PATCH 04/21] Fix case issue --- Firmware/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firmware/README.md b/Firmware/README.md index e1b60ef9..ac9246b1 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -12,7 +12,7 @@ If you are a developer, you are encouraged to use the `devel` branch, as it cont - [Compiling and downloading firmware](#compiling-and-downloading-firmware) - [Communicating over USB or UART](#communicating-over-usb-or-uart) - [Generating startup code](#generating-startup-code) -- [Setting up an IDE](#setting-up-an-IDE) +- [Setting up an IDE](#setting-up-an-ide) - [Notes for Contributors](#notes-for-contributors) From 2888c83de82c554e10dee5a39e6c54292fc44baf Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:32:11 -0500 Subject: [PATCH 05/21] Fix table of contents order --- Firmware/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Firmware/README.md b/Firmware/README.md index ac9246b1..11d59c6f 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -10,9 +10,10 @@ If you are a developer, you are encouraged to use the `devel` branch, as it cont - [Configuring parameters](#configuring-parameters) - [Compiling and downloading firmware](#compiling-and-downloading-firmware) +- [Setting up an IDE](#setting-up-an-ide) +- [Continuing without an IDE](#no-ide-instructions) - [Communicating over USB or UART](#communicating-over-usb-or-uart) - [Generating startup code](#generating-startup-code) -- [Setting up an IDE](#setting-up-an-ide) - [Notes for Contributors](#notes-for-contributors) From 039e0481d6cd45c6c495f5f5b1ce91021e099bcf Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:32:23 -0500 Subject: [PATCH 06/21] Make document links relative --- Firmware/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firmware/README.md b/Firmware/README.md index 11d59c6f..82162081 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -170,7 +170,7 @@ pip install pyusb pyserial [See ODrive Arduino Library](https://github.com/madcowswe/ODriveArduino) ### Other platforms -See the [protocol specification](https://github.com/madcowswe/ODrive/blob/devel/Firmware/protocol.md) or the [legacy protocol specification](https://github.com/madcowswe/ODrive/blob/devel/Firmware/legacy-protocol.md). +See the [protocol specification](protocol.md) or the [legacy protocol specification](legacy-protocol.md). ## Generating startup code From ecbf0281e5715c12208af0b0650cafd55bb8d027 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:33:14 -0500 Subject: [PATCH 07/21] Test relative doc link --- Firmware/configuring-vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index 5b5abf4a..c8f48401 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -2,7 +2,7 @@ VSCode is the recommended IDE for working with the ODrive codebase. It is a light-weight text editor with Git integration and GDB debugging functionality. -Before doing the VSCode setup, make sure you've installed all of your [prerequisites](README.md#installing-prerequisites) +Before doing the VSCode setup, make sure you've installed all of your [prerequisites](#installing-prerequisites) --- ## Setup Procedure From fec41cfa08e1b36b162639d825d3b29080963a1f Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:33:44 -0500 Subject: [PATCH 08/21] Revert Test relative doc link --- Firmware/configuring-vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index c8f48401..5b5abf4a 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -2,7 +2,7 @@ VSCode is the recommended IDE for working with the ODrive codebase. It is a light-weight text editor with Git integration and GDB debugging functionality. -Before doing the VSCode setup, make sure you've installed all of your [prerequisites](#installing-prerequisites) +Before doing the VSCode setup, make sure you've installed all of your [prerequisites](README.md#installing-prerequisites) --- ## Setup Procedure From c073c6eb4b81d1a91a89990bca709f3f9b0c0792 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:35:59 -0500 Subject: [PATCH 09/21] Tweak formatting --- Firmware/configuring-eclipse.md | 10 +++++----- Firmware/configuring-vscode.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Firmware/configuring-eclipse.md b/Firmware/configuring-eclipse.md index 25da57e2..e4576255 100644 --- a/Firmware/configuring-eclipse.md +++ b/Firmware/configuring-eclipse.md @@ -1,10 +1,10 @@ -## Setting up Eclipse development environment +# Setting up Eclipse development environment -### Install +## Install * Install [Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neon3) * Install the [OpenOCD Eclipse plugin](http://gnuarmeclipse.github.io/plugins/install/) -### Import project +## Import project * File -> Import -> C/C++ -> Existing Code as Makefile Project * Browse for existing code location, find the OdriveFirmware root. * In the Toolchain options, select `Cross GCC` @@ -13,7 +13,7 @@ ![Toolchain options](screenshots/CodeAsMakefile.png "Toolchain options") -### Load the launch configuration +## Load the launch configuration * File -> Import -> Run/Debug -> Launch Configurations -> Next * Highlight (don't tick) the OdriveFirmare folder in the left column * Tick OdriveFirmware.launch in the right column @@ -21,7 +21,7 @@ ![Launch Configurations](screenshots/ImportLaunch.png "Launch Configurations") -### Launch! +## Launch! * Make sure the programmer is connected to the board as per [Flashing the firmware](#flashing-the-firmware). * Press the down-arrow of the debug symbol in the toolbar, and hit Debug Configurations * You can also hit Run -> Debug Configurations diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index 5b5abf4a..f2b54ee4 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -4,10 +4,10 @@ VSCode is the recommended IDE for working with the ODrive codebase. It is a lig Before doing the VSCode setup, make sure you've installed all of your [prerequisites](README.md#installing-prerequisites) ---- ## Setup Procedure 1. Clone the ODrive repository 1. [Download VSCode](https://code.visualstudio.com/download) +1. Open VSCode 1. Install extensions. This can be done directly from VSCode (Ctrl+Shift+X) * Required extensions: * C/C++ From c24929842c14ed67c45a9e074c028f034f048ab6 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:38:01 -0500 Subject: [PATCH 10/21] Minor readme formatting --- Firmware/configuring-vscode.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index f2b54ee4..62368874 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -44,7 +44,8 @@ The solution we have is not the most elegant, and if you know a better way, plea * The processor will reset and halt. * Set your breakpoints. Note: you can only set breakpoints when the processor is halted, if you set them during run mode, they won't get applied. * Run - * When you are done, you must kill the openocd task before you are able to flash the board again: Tasks -> Terminate task -> openocd. + * When you are done, you must kill the openocd task before you are able to flash the board again: + * Tasks -> Terminate task -> openocd ## Cleaning the Build This sometimes needs to be done if you change branches. From 1a8a3f5531b85fbbc6877fb9b8724165bfa68122 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:39:28 -0500 Subject: [PATCH 11/21] Add lines for section clarity --- Firmware/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Firmware/README.md b/Firmware/README.md index 82162081..1e1acc2b 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -172,7 +172,7 @@ pip install pyusb pyserial ### Other platforms See the [protocol specification](protocol.md) or the [legacy protocol specification](legacy-protocol.md). - +--- ## Generating startup code **Note:** You do not need to run this step to program the board. This is only required if you wish to update the auto generated code. @@ -188,6 +188,7 @@ You will likely want the pinout for this process. It is available [here](https:/ * Press `Project -> Generate code` * You may need to let it download some drivers and such. +--- ## Notes for Contributors In general the project uses the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html), except that the default indendtation is 4 spaces, and that the 80 character limit is not very strictly enforced, merely encouraged. From 2885903e71a1c476f3a45cda1fed7c7a38e6990f Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:47:09 -0500 Subject: [PATCH 12/21] Test nbsp markdown rendering on github --- Firmware/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Firmware/README.md b/Firmware/README.md index 1e1acc2b..193f851b 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -172,7 +172,8 @@ pip install pyusb pyserial ### Other platforms See the [protocol specification](protocol.md) or the [legacy protocol specification](legacy-protocol.md). ---- +  + ## Generating startup code **Note:** You do not need to run this step to program the board. This is only required if you wish to update the auto generated code. From 45ed130a324af2cf08002ba65a1f000085e96bb9 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Tue, 28 Nov 2017 19:48:37 -0500 Subject: [PATCH 13/21] Replace --- with html breaks --- Firmware/README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Firmware/README.md b/Firmware/README.md index 193f851b..585aae4c 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -88,7 +88,7 @@ An upcoming feature will enable automatic tuning. Until then, here is a rough tu By default both motors are enabled, and the default control mode is position control. If you want a different mode, you can change `.control_mode`. To disable a motor, set `.enable_control` and `.do_calibration` to false. ----- +

## Compiling and downloading firmware ### Getting a programmer Get a programmer that supports SWD (Serial Wire Debugging) and is ST-link v2 compatible. You can get them really cheap on [eBay](http://www.ebay.co.uk/itm/ST-Link-V2-Emulator-Downloader-Programming-Mini-Unit-STM8-STM32-with-20CM-Line-/391173940927?hash=item5b13c8a6bf:g:3g8AAOSw~OdVf-Tu) or many other places. @@ -116,14 +116,14 @@ Install the following: * [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm). Make is used to script the compilation process. Download and run the complete package setup program. Add the path of the binaries to your PATH environment variable. For me this was at `C:\Program Files (x86)\GnuWin32\bin`. For details on how to set your path envirment in windows see [these instructions.](https://www.java.com/en/download/help/path.xml) * OpenOCD. Follow the instructions at [GNU ARM Eclipse - How to install the OpenOCD binaries](http://gnuarmeclipse.github.io/openocd/install/), including the part about ST-LINK/V2 drivers. Add the path of the binaries to your PATH environment variable. For me this was at `C:\Program Files\GNU ARM Eclipse\OpenOCD\0.10.0-201704182147-dev\bin`. ---- +

## Setting up an IDE ODrive is a Makefile project. It does not require an IDE, but the open-source VSCode is recommended. It is also possible to use Eclipse. If you'd like to go that route, please see the respective configuration document: * [Configuring VSCode](configuring-vscode.md) * [Configuring Eclipse](configuring-eclipse.md) ---- +

## No IDE Instructions After installing all of the above, open a Git Bash shell. Continue at section [Building the firmware](#building-the-firmware). @@ -143,7 +143,7 @@ If the flashing worked, you can start sending commands. If you want to do that n ### Debugging the firmware * Run `make gdb`. This will reset and halt at program start. Now you can set breakpoints and run the program. If you know how to use gdb, you are good to go. ---- +

## Communicating over USB or UART ### From Linux/Windows/macOS There are two simple python scripts to help you get started with controlling the ODrive using python. @@ -172,8 +172,7 @@ pip install pyusb pyserial ### Other platforms See the [protocol specification](protocol.md) or the [legacy protocol specification](legacy-protocol.md). -  - +

## Generating startup code **Note:** You do not need to run this step to program the board. This is only required if you wish to update the auto generated code. @@ -189,7 +188,7 @@ You will likely want the pinout for this process. It is available [here](https:/ * Press `Project -> Generate code` * You may need to let it download some drivers and such. ---- +

## Notes for Contributors In general the project uses the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html), except that the default indendtation is 4 spaces, and that the 80 character limit is not very strictly enforced, merely encouraged. From b1d8a25ba1742dd5b042a35d33e8eb3608f40efd Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Fri, 1 Dec 2017 22:06:58 -0500 Subject: [PATCH 14/21] Grammar --- Firmware/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firmware/README.md b/Firmware/README.md index 585aae4c..810a5082 100644 --- a/Firmware/README.md +++ b/Firmware/README.md @@ -118,7 +118,7 @@ Install the following:

## Setting up an IDE -ODrive is a Makefile project. It does not require an IDE, but the open-source VSCode is recommended. It is also possible to use Eclipse. If you'd like to go that route, please see the respective configuration document: +ODrive is a Makefile project. It does not require an IDE, but the open-source IDE VSCode is recommended. It is also possible to use Eclipse. If you'd like to go that route, please see the respective configuration document: * [Configuring VSCode](configuring-vscode.md) * [Configuring Eclipse](configuring-eclipse.md) From 84d7ced0430f7e7dfb8b4569d16df1bf156e9fe5 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Sat, 13 Jan 2018 12:25:59 -0500 Subject: [PATCH 15/21] Add Cortex-Debug debugging configuration --- Firmware/.vscode/launch.json | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/Firmware/.vscode/launch.json b/Firmware/.vscode/launch.json index f6e36562..e77ffee8 100644 --- a/Firmware/.vscode/launch.json +++ b/Firmware/.vscode/launch.json @@ -4,6 +4,20 @@ // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 "version": "0.2.0", "configurations": [ + { + // For the Cortex-Debug extension + "type": "openocd-gdb", + "request": "launch", + "name": "Debug Microcontroller", + "gdbpath": "arm-none-eabi-gdb", + "executable": "${workspaceRoot}/build/ODriveFirmware.elf", + "configFiles": [ + "interface/stlink-v2.cfg", + "target/stm32f4x_stlink.cfg", + ], + "cwd": "${workspaceRoot}" + }, + // For the Native Debug extension { "type": "gdb", "request": "attach", @@ -14,7 +28,6 @@ "executable": "./build/ODriveFirmware.elf", "cwd": "${workspaceRoot}", "printCalls": false, - //"preLaunchTask": "openocd", // This isn't working quite right. "autorun": [ "monitor reset halt" ] From 14832e1ab09bb31dcf323df134384995a11c50d1 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Sat, 13 Jan 2018 12:37:52 -0500 Subject: [PATCH 16/21] Change VSCode documentation to reflect Cortex-Debug --- Firmware/configuring-vscode.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index 62368874..0b2950c8 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -11,8 +11,8 @@ Before doing the VSCode setup, make sure you've installed all of your [prerequis 1. Install extensions. This can be done directly from VSCode (Ctrl+Shift+X) * Required extensions: * C/C++ - * Native Debug * Recommended Extensions: + * Cortex-Debug * vscode-icons * Code Outline * Include Autocomplete @@ -36,16 +36,17 @@ A terminal window will open with your native shell. VSCode is configured to run If the flashing worked, you can start sending commands. If you want to do that now, you can go to [Communicating over USB or UART](README.md#communicating-over-usb-or-uart). ## Debugging -The solution we have is not the most elegant, and if you know a better way, please do help us. +An extension called Cortex-Debug has recently been released which is designed specifically for debugging ARM Cortex projects. You can read more on Cortex-Debug here: https://github.com/Marus/cortex-debug + +Note: If developing on Windows, you should have `arm-none-eabi-gdb` and `openOCD` on your PATH. + * Make sure you have the Firmware folder as your active folder * Flash the board with the newest code (starting debug session doesn't do this) - * Tasks -> Run Task -> openocd - * Debug -> Start Debugging + * Debug -> Start Debugging (or press F5) * The processor will reset and halt. * Set your breakpoints. Note: you can only set breakpoints when the processor is halted, if you set them during run mode, they won't get applied. * Run - * When you are done, you must kill the openocd task before you are able to flash the board again: - * Tasks -> Terminate task -> openocd + * When done debugging, simply halt the debugger. It will kill your ## Cleaning the Build This sometimes needs to be done if you change branches. From 0376f3993d9d98a8f63134373b1883ec78ade044 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Sat, 13 Jan 2018 12:38:37 -0500 Subject: [PATCH 17/21] Remove Native Debug configuration --- Firmware/.vscode/launch.json | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/Firmware/.vscode/launch.json b/Firmware/.vscode/launch.json index e77ffee8..38053439 100644 --- a/Firmware/.vscode/launch.json +++ b/Firmware/.vscode/launch.json @@ -17,20 +17,5 @@ ], "cwd": "${workspaceRoot}" }, - // For the Native Debug extension - { - "type": "gdb", - "request": "attach", - "name": "Debug Firmware", - "target": "localhost:3333", - "gdbpath": "arm-none-eabi-gdb", - "remote": true, - "executable": "./build/ODriveFirmware.elf", - "cwd": "${workspaceRoot}", - "printCalls": false, - "autorun": [ - "monitor reset halt" - ] - } ] } \ No newline at end of file From 85a802dc4cec0b17d6cd3e74234bad504e0591fd Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Sat, 13 Jan 2018 12:39:08 -0500 Subject: [PATCH 18/21] Remove gdbPath variable. Cortex-Debug already handles it --- Firmware/.vscode/launch.json | 1 - 1 file changed, 1 deletion(-) diff --git a/Firmware/.vscode/launch.json b/Firmware/.vscode/launch.json index 38053439..6cd5be0b 100644 --- a/Firmware/.vscode/launch.json +++ b/Firmware/.vscode/launch.json @@ -9,7 +9,6 @@ "type": "openocd-gdb", "request": "launch", "name": "Debug Microcontroller", - "gdbpath": "arm-none-eabi-gdb", "executable": "${workspaceRoot}/build/ODriveFirmware.elf", "configFiles": [ "interface/stlink-v2.cfg", From 05b374fb18e9fb205f7d4c6044e4adc1bf7b4f03 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Sat, 13 Jan 2018 12:40:56 -0500 Subject: [PATCH 19/21] Rename the debug config to Debug ODrive --- Firmware/.vscode/launch.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firmware/.vscode/launch.json b/Firmware/.vscode/launch.json index 6cd5be0b..747e4f1a 100644 --- a/Firmware/.vscode/launch.json +++ b/Firmware/.vscode/launch.json @@ -8,7 +8,7 @@ // For the Cortex-Debug extension "type": "openocd-gdb", "request": "launch", - "name": "Debug Microcontroller", + "name": "Debug ODrive", "executable": "${workspaceRoot}/build/ODriveFirmware.elf", "configFiles": [ "interface/stlink-v2.cfg", From 06977066d1c06689817d82d82dab2318e96fe608 Mon Sep 17 00:00:00 2001 From: Paul Guenette Date: Sat, 13 Jan 2018 12:54:37 -0500 Subject: [PATCH 20/21] Add more info on controlling the debugger --- Firmware/configuring-vscode.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Firmware/configuring-vscode.md b/Firmware/configuring-vscode.md index 0b2950c8..ec9b0adb 100644 --- a/Firmware/configuring-vscode.md +++ b/Firmware/configuring-vscode.md @@ -45,8 +45,9 @@ Note: If developing on Windows, you should have `arm-none-eabi-gdb` and `openOCD * Debug -> Start Debugging (or press F5) * The processor will reset and halt. * Set your breakpoints. Note: you can only set breakpoints when the processor is halted, if you set them during run mode, they won't get applied. - * Run - * When done debugging, simply halt the debugger. It will kill your + * Run (F5) + * Stepping over/in/out, restarting, and changing breakpoints can be done by first pressing the "pause" (F6) button at the top the screen. + * When done debugging, simply stop (Shift+F5) the debugger. It will kill your openOCD process too. ## Cleaning the Build This sometimes needs to be done if you change branches. From d8b649d8f075f53dbd3c8a181c83772fd051db54 Mon Sep 17 00:00:00 2001 From: Oskar Weigl Date: Wed, 17 Jan 2018 23:47:31 -0800 Subject: [PATCH 21/21] update CHANGELOG.md --- Firmware/CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Firmware/CHANGELOG.md b/Firmware/CHANGELOG.md index 7ddb3bba..4f95421e 100644 --- a/Firmware/CHANGELOG.md +++ b/Firmware/CHANGELOG.md @@ -1,3 +1,12 @@ +## UNRELEASED + +### Added +* Getting started instructions for VSCode + +### Changed +* Recommended method to debug firmware from VSCode now uses Cortex-Debug extension instead of native-debug. +* Refactor IDE instructions into separate files + ## [0.3] - 2017-12-18 ### Added * **New binary communication protocol**