diff --git a/docs/reStructuredText/can-guide.rst b/docs/reStructuredText/can-guide.rst index 4e3f9aac..9451251f 100644 --- a/docs/reStructuredText/can-guide.rst +++ b/docs/reStructuredText/can-guide.rst @@ -4,6 +4,10 @@ CAN Bus Guide for ODrive ================================================================================ +.. contents:: + :depth: 1 + :local: + ODrive v3 supports CAN 2.0b. We've built a :ref:`simple protocol ` (named CANSimple) so that most ODrive functions can be controlled without a full CAN Open or similar stack. This guide is intended for beginners to set up CAN on the ODrive and on their host device. We will be focusing on Raspberry Pi and Arduino-compatible devices using the MCP2515 CAN Controller. @@ -192,8 +196,8 @@ A DBC file (.dbc) is a database of all the messages and signals in a CAN protoco This file can be used with Python cantools to serialize and deserialize messages without having to handle the bitshifting etc yourself. We have generated a .dbc for CANSimple for you! -* :ref:`CANSimple DBC File <../tools/odrive-cansimple.dbc>` -* :ref:`CANSimple DBC Generator Script <../tools/create_can_dbc.py>` +* `CANSimple DBC File `_ +* `CANSimple DBC Generator Script `_ Instead of manually writing values into the data, we can create a dictionary of signal:value pairs and serialize the data according to the database definition. @@ -201,6 +205,6 @@ Instead of manually writing values into the data, we can create a dictionary of #. Use :code:`encode_message()` to get a byte array representation of data for sending #. Use :code:`decode_message()` to get a dictionary representation of data for receiving -The :ref:`CAN DBC Example <../tools/can_dbc_example.py>` script shows you how this can be used. This is the recommended method of serializing and deserializing. +The `CAN DBC Example `_ script shows you how this can be used. This is the recommended method of serializing and deserializing. -If you're using C++, then you can use the :ref:`CANHelpers <..firmware/communication/../../../Firmware/communication/can/can_helpers.hpp>` single-header library to do this instead, although the DBC file isn't used. +If you're using C++, then you can use the `CANHelpers `_ single-header library to do this instead, although the DBC file isn't used. diff --git a/docs/reStructuredText/can-protocol.rst b/docs/reStructuredText/can-protocol.rst index 7816f5e1..d3c71b02 100644 --- a/docs/reStructuredText/can-protocol.rst +++ b/docs/reStructuredText/can-protocol.rst @@ -4,6 +4,10 @@ CAN Protocol ================================================================================ +.. contents:: + :depth: 1 + :local: + This document describes the CAN Protocol. For examples of usage, check out our :ref:`CAN Guide! ` diff --git a/docs/reStructuredText/configuring-eclipse.rst b/docs/reStructuredText/configuring-eclipse.rst index a6deb576..81e8854c 100644 --- a/docs/reStructuredText/configuring-eclipse.rst +++ b/docs/reStructuredText/configuring-eclipse.rst @@ -4,6 +4,10 @@ Setting up Eclipse development environment ================================================================================ +.. contents:: + :depth: 1 + :local: + Install ------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/configuring-vscode.rst b/docs/reStructuredText/configuring-vscode.rst index 3be2f09b..44175225 100644 --- a/docs/reStructuredText/configuring-vscode.rst +++ b/docs/reStructuredText/configuring-vscode.rst @@ -4,6 +4,10 @@ Configuring Visual Studio Code ================================================================================ +.. contents:: + :depth: 1 + :local: + 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. diff --git a/docs/reStructuredText/control.rst b/docs/reStructuredText/control.rst index 95b26840..e5430561 100644 --- a/docs/reStructuredText/control.rst +++ b/docs/reStructuredText/control.rst @@ -4,6 +4,10 @@ Control Structure and Tuning ================================================================================ +.. contents:: + :depth: 1 + :local: + The motor controller is a cascaded style position, velocity and current control loop, as per the diagram below. When the control mode is set to position control, the whole loop runs. When running in velocity control mode, the position control part is removed and the velocity command is fed directly in to the second stage input. diff --git a/docs/reStructuredText/developer-guide.rst b/docs/reStructuredText/developer-guide.rst index f91c0adb..cdcf4085 100644 --- a/docs/reStructuredText/developer-guide.rst +++ b/docs/reStructuredText/developer-guide.rst @@ -14,7 +14,7 @@ As such it assumes that you know things like how to use Git, what a compiler is, The official releases are maintained on the `master` branch. However since you are a developer, you are encouraged to use the `devel` branch, as it contains the latest features. -The project is under active development, so make sure to check the :ref:`Changelog <../CHANGELOG.md>` to keep track of updates. +The project is under active development, so make sure to check the `Changelog `_ to keep track of updates. .. _dev-prereq: @@ -475,5 +475,5 @@ When filing a PR please go through this checklist: * Also, for each removed/moved/renamed API item use your IDE's search feature to search for occurrences of this name. Update the places you found (this will usually be documentation and test scripts). * If you added things to :code:`odrive-interface.yaml` make sure the new things have decent documentation in the YAML file. We don't expect 100% coverage but use good sense of what to document. * Make sure your PR doesn't contain spurious changes that unnecessarily add or remove whitespace. These add noise and make the reviewer's lifes harder. - * If you changed any enums in :code:`odrive-interface.yaml`, make sure you update :ref:`enums.py <../tools/odrive/enums.py>` and :ref:`ODriveEnums.h <../Arduino/ODriveArduino/ODriveEnums.h>`. + * If you changed any enums in :code:`odrive-interface.yaml`, make sure you update `enums.py `_ and `ODriveEnums.h `_. The file includes instructions on how to do this. Check the diff to verify that none of the existing enumerators changed their value. diff --git a/docs/reStructuredText/encoders.rst b/docs/reStructuredText/encoders.rst index 7a20c1f7..cfd22383 100644 --- a/docs/reStructuredText/encoders.rst +++ b/docs/reStructuredText/encoders.rst @@ -2,6 +2,10 @@ Encoders ================================================================================ +.. contents:: + :depth: 1 + :local: + Known and Supported Encoders -------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/endstops.rst b/docs/reStructuredText/endstops.rst index 40a903cd..56fcf119 100644 --- a/docs/reStructuredText/endstops.rst +++ b/docs/reStructuredText/endstops.rst @@ -2,6 +2,10 @@ Endstops and Homing ================================================================================ +.. contents:: + :depth: 1 + :local: + By default, the ODrive assumes that your motor encoder's zero position is the same as your machine's zero position, but in real life this is rarely the case. In these systems it is useful to allow your motor to move until a physical or electronic device orders the system to stop. That `endstop` can be used as a known reference point. Once the ODrive has hit that position it may then want to move to a final zero, or `home`, position. diff --git a/docs/reStructuredText/getting-started.rst b/docs/reStructuredText/getting-started.rst index 9de14de2..7efa2398 100644 --- a/docs/reStructuredText/getting-started.rst +++ b/docs/reStructuredText/getting-started.rst @@ -547,7 +547,7 @@ Upgrading from 0.4.12 -------------------------------------------------------------------------------- A new version (0.5.4) of ODrive firmware has released, complete with a new odrivetool. -Follow the installation instructions, making sure to add the :code:`--upgrade` flag to pip commands, and check out the :ref:`Changelog <../CHANGELOG.md>` for changes! +Follow the installation instructions, making sure to add the :code:`--upgrade` flag to pip commands, and check out the `Changelog `_ for changes! The odrivetool will stage and restore your configuration. This probably isn't wise for the 0.4.12 -> 0.5.1 upgrade, so we suggest using :code:`odrv0.erase_configuration()` immediately after connecting the first time. diff --git a/docs/reStructuredText/ground-loops.rst b/docs/reStructuredText/ground-loops.rst index ee362aeb..7ee93566 100644 --- a/docs/reStructuredText/ground-loops.rst +++ b/docs/reStructuredText/ground-loops.rst @@ -5,6 +5,10 @@ Ground Loops ================================================================================ +.. contents:: + :depth: 1 + :local: + For electrical devices to communicate, most of the time they require a common ground connection. Best practice is to connect the grounds back to a single point, called a "star ground". If there are multiple paths to ground, a "ground loop" is formed. diff --git a/docs/reStructuredText/hoverboard.rst b/docs/reStructuredText/hoverboard.rst index 56ffd9ba..0ef39a3e 100644 --- a/docs/reStructuredText/hoverboard.rst +++ b/docs/reStructuredText/hoverboard.rst @@ -5,6 +5,10 @@ Hoverboard motor and remote control setup guide ================================================================================ +.. contents:: + :depth: 1 + :local: + By popular request here follows a step-by-step guide on how to setup the ODrive to drive hoverboard motors using RC PWM input. Each step is accompanied by some explanation so hopefully you can carry over some of the steps to other setups and configurations. diff --git a/docs/reStructuredText/migration.rst b/docs/reStructuredText/migration.rst index 3b41e423..7bd6cb7d 100644 --- a/docs/reStructuredText/migration.rst +++ b/docs/reStructuredText/migration.rst @@ -2,6 +2,10 @@ Migration Guide ================================================================================ +.. contents:: + :depth: 1 + :local: + v0.5.1 -> v0.5.2 -------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/native-protocol.rst b/docs/reStructuredText/native-protocol.rst index 1a2850cb..122eef27 100644 --- a/docs/reStructuredText/native-protocol.rst +++ b/docs/reStructuredText/native-protocol.rst @@ -22,7 +22,7 @@ Assuming you already installed the odrive library (:code:`pip install odrive`), print(str(odrv0.vbus_voltage)) -For a more comprehensive example, see :ref:`tools/odrive_demo.py <../tools/odrive_demo.py>`. +For a more comprehensive example, see `tools/odrive_demo.py `_. Other Languages -------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/odrivetool.rst b/docs/reStructuredText/odrivetool.rst index ed69a849..f2d170e6 100644 --- a/docs/reStructuredText/odrivetool.rst +++ b/docs/reStructuredText/odrivetool.rst @@ -4,6 +4,10 @@ :code:`odrivetool` ================================================================================ +.. contents:: + :depth: 1 + :local: + The :code:`odrivetool` is the accompanying PC program for the ODrive. It's main purpose is to provide an interactive shell to control the device manually, as well as some supporting functions like firmware update. Installation diff --git a/docs/reStructuredText/pinout.rst b/docs/reStructuredText/pinout.rst index 02a9002f..5ab79ec5 100644 --- a/docs/reStructuredText/pinout.rst +++ b/docs/reStructuredText/pinout.rst @@ -4,6 +4,10 @@ ODrive v3.x Pinout ================================================================================ +.. contents:: + :depth: 1 + :local: + .. ODrive v4.1 .. -------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/protocol.rst b/docs/reStructuredText/protocol.rst index fb07e914..a0fda573 100644 --- a/docs/reStructuredText/protocol.rst +++ b/docs/reStructuredText/protocol.rst @@ -4,6 +4,10 @@ ODrive Communication Protocol ================================================================================ +.. contents:: + :depth: 1 + :local: + Communicating with an ODrive consists of a series of endpoint operations. An endpoint can theoretically be any kind data serialized in any way. There is a default serialization implementation for POD types; for custom types diff --git a/docs/reStructuredText/rc-pwm.rst b/docs/reStructuredText/rc-pwm.rst index 94080602..2ba29f49 100644 --- a/docs/reStructuredText/rc-pwm.rst +++ b/docs/reStructuredText/rc-pwm.rst @@ -4,6 +4,10 @@ RC PWM input ================================================================================ +.. contents:: + :depth: 1 + :local: + You can control the ODrive directly from a hobby RC receiver. Any of the numerical parameters that are writable from the ODrive Tool can be hooked up to a PWM input. diff --git a/docs/reStructuredText/specifications.rst b/docs/reStructuredText/specifications.rst index 6eb46a0b..83fc40d9 100644 --- a/docs/reStructuredText/specifications.rst +++ b/docs/reStructuredText/specifications.rst @@ -2,6 +2,10 @@ Specifications ================================================================================ +.. contents:: + :depth: 1 + :local: + Electrical Specifications -------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/step-direction.rst b/docs/reStructuredText/step-direction.rst index 401e8a45..de446fcb 100644 --- a/docs/reStructuredText/step-direction.rst +++ b/docs/reStructuredText/step-direction.rst @@ -2,6 +2,10 @@ Step/Direction ================================================================================ +.. contents:: + :depth: 1 + :local: + This is the simplest possible way of controlling the ODrive. It is also the most primitive and fragile one. So don't use it unless you must interoperate with other hardware that you don't control. diff --git a/docs/reStructuredText/testing.rst b/docs/reStructuredText/testing.rst index 4f3a75b1..1ab39827 100644 --- a/docs/reStructuredText/testing.rst +++ b/docs/reStructuredText/testing.rst @@ -2,6 +2,9 @@ Automated Testing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. contents:: + :depth: 1 + :local: This section describes how to use the automated testing facilities. You don't have to do this as an end user. @@ -186,7 +189,7 @@ To flash and start remote debugging: ssh -t odrv -L3333:localhost:3333 bash -c "\"openocd '-f' 'interface/stlink-v2.cfg' '-f' 'target/stm32f4x_stlink.cfg'\"" - You can keep this open for multiple debug sessions. Press :kbd:`Ctrl` **+** :kbd:`C`to quit. + You can keep this open for multiple debug sessions. Press :kbd:`Ctrl` **+** :kbd:`C` to quit. #. Compile the firmware. #. In VSCode, select the run configuration "Debug ODrive v3.x/v4.x - Remote" and press Run. This will flash the new firmware before dropping you into the debugger. diff --git a/docs/reStructuredText/thermistors.rst b/docs/reStructuredText/thermistors.rst index 0ebe6bc9..8ffd5df6 100644 --- a/docs/reStructuredText/thermistors.rst +++ b/docs/reStructuredText/thermistors.rst @@ -4,6 +4,10 @@ Thermistors ================================================================================ +.. contents:: + :depth: 1 + :local: + Introduction -------------------------------------------------------------------------------- diff --git a/docs/reStructuredText/troubleshooting.rst b/docs/reStructuredText/troubleshooting.rst index 7369b593..dacbf454 100644 --- a/docs/reStructuredText/troubleshooting.rst +++ b/docs/reStructuredText/troubleshooting.rst @@ -4,6 +4,10 @@ Troubleshooting ================================================================================ +.. contents:: + :depth: 1 + :local: + .. _error-codes: Error Codes