mirror of
https://github.com/odriverobotics/ODrive.git
synced 2026-02-06 07:01:52 +08:00
moved reST into docs, fixed API table
This commit is contained in:
nick-a-schneider
4
.github/workflows/documentation.yml
vendored
4
.github/workflows/documentation.yml
vendored
@@ -25,14 +25,14 @@ jobs:
|
||||
|
||||
- name: Build HTML docs
|
||||
run: |
|
||||
cd docs/reStructuredText
|
||||
cd docs
|
||||
make html
|
||||
|
||||
- name: Upload docs
|
||||
uses: ./.github/actions/upload-release
|
||||
with:
|
||||
release_type: docs
|
||||
src_dir: docs/reStructuredText/_build/html
|
||||
src_dir: docs/_build/html
|
||||
do_access_key: ${{ secrets.DIGITALOCEAN_ACCESS_KEY }}
|
||||
do_secret_key: ${{ secrets.DIGITALOCEAN_SECRET_KEY }}
|
||||
odrive_api_key: ${{ secrets.ODRIVE_API_KEY }}
|
||||
|
||||
@@ -259,23 +259,38 @@ interfaces:
|
||||
|
||||
Here's an (incomplete) list of baudrates for ODrive v3.x:
|
||||
|
||||
Configured | Actual | Error [%]
|
||||
-------------|---------------|-----------
|
||||
1.2 KBps | 1.2 KBps | 0
|
||||
2.4 KBps | 2.4 KBps | 0
|
||||
9.6 KBps | 9.6 KBps | 0
|
||||
19.2 KBps | 19.195 KBps | 0.02
|
||||
38.4 KBps | 38.391 KBps | 0.02
|
||||
57.6 KBps | 57.613 KBps | 0.02
|
||||
115.2 KBps | 115.068 KBps | 0.11
|
||||
230.4 KBps | 230.769 KBps | 0.16
|
||||
460.8 KBps | 461.538 KBps | 0.16
|
||||
921.6 KBps | 913.043 KBps | 0.93
|
||||
1.792 MBps | 1.826 MBps | 1.9
|
||||
1.8432 MBps | 1.826 MBps | 0.93
|
||||
+-------------+---------------+-----------+
|
||||
| Configured | Actual | Error [%] |
|
||||
+=============+===============+===========+
|
||||
| 1.2 KBps | 1.2 KBps | 0 |
|
||||
+-------------+---------------+-----------+
|
||||
| 2.4 KBps | 2.4 KBps | 0 |
|
||||
+-------------+---------------+-----------+
|
||||
| 9.6 KBps | 9.6 KBps | 0 |
|
||||
+-------------+---------------+-----------+
|
||||
| 19.2 KBps | 19.195 KBps | 0.02 |
|
||||
+-------------+---------------+-----------+
|
||||
| 38.4 KBps | 38.391 KBps | 0.02 |
|
||||
+-------------+---------------+-----------+
|
||||
| 57.6 KBps | 57.613 KBps | 0.02 |
|
||||
+-------------+---------------+-----------+
|
||||
| 115.2 KBps | 115.068 KBps | 0.11 |
|
||||
+-------------+---------------+-----------+
|
||||
| 230.4 KBps | 230.769 KBps | 0.16 |
|
||||
+-------------+---------------+-----------+
|
||||
| 460.8 KBps | 461.538 KBps | 0.16 |
|
||||
+-------------+---------------+-----------+
|
||||
| 921.6 KBps | 913.043 KBps | 0.93 |
|
||||
+-------------+---------------+-----------+
|
||||
| 1.792 MBps | 1.826 MBps | 1.9 |
|
||||
+-------------+---------------+-----------+
|
||||
| 1.8432 MBps | 1.826 MBps | 0.93 |
|
||||
+-------------+---------------+-----------+
|
||||
|
||||
|
||||
For more information refer to Section 30.3.4 and Table 142 (the column with f_PCLK = 42 MHz) in the
|
||||
[STM datasheet](https://www.st.com/content/ccc/resource/technical/document/reference_manual/3d/6d/5a/66/b4/99/40/d4/DM00031020.pdf/files/DM00031020.pdf/jcr:content/translations/en.DM00031020.pdf).
|
||||
`STM datasheet <https://www.st.com/content/ccc/resource/technical/document/reference_manual/3d/6d/5a/66/b4/99/40/d4/DM00031020.pdf/files/DM00031020.pdf/jcr:content/translations/en.DM00031020.pdf>`__.
|
||||
|
||||
uart_b_baudrate:
|
||||
type: uint32
|
||||
unit: baud/s
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
docs.odriverobotics.com
|
||||
@@ -1,3 +0,0 @@
|
||||
source 'https://rubygems.org'
|
||||
gem 'github-pages', group: :jekyll_plugins
|
||||
gem 'jekyll-redirect-from'
|
||||
@@ -1,283 +0,0 @@
|
||||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
activesupport (6.0.3.7)
|
||||
concurrent-ruby (~> 1.0, >= 1.0.2)
|
||||
i18n (>= 0.7, < 2)
|
||||
minitest (~> 5.1)
|
||||
tzinfo (~> 1.1)
|
||||
zeitwerk (~> 2.2, >= 2.2.2)
|
||||
addressable (2.8.0)
|
||||
public_suffix (>= 2.0.2, < 5.0)
|
||||
coffee-script (2.4.1)
|
||||
coffee-script-source
|
||||
execjs
|
||||
coffee-script-source (1.11.1)
|
||||
colorator (1.1.0)
|
||||
commonmarker (0.17.13)
|
||||
ruby-enum (~> 0.5)
|
||||
concurrent-ruby (1.1.8)
|
||||
dnsruby (1.61.5)
|
||||
simpleidn (~> 0.1)
|
||||
em-websocket (0.5.2)
|
||||
eventmachine (>= 0.12.9)
|
||||
http_parser.rb (~> 0.6.0)
|
||||
ethon (0.14.0)
|
||||
ffi (>= 1.15.0)
|
||||
eventmachine (1.2.7)
|
||||
execjs (2.8.1)
|
||||
faraday (1.4.2)
|
||||
faraday-em_http (~> 1.0)
|
||||
faraday-em_synchrony (~> 1.0)
|
||||
faraday-excon (~> 1.1)
|
||||
faraday-net_http (~> 1.0)
|
||||
faraday-net_http_persistent (~> 1.1)
|
||||
multipart-post (>= 1.2, < 3)
|
||||
ruby2_keywords (>= 0.0.4)
|
||||
faraday-em_http (1.0.0)
|
||||
faraday-em_synchrony (1.0.0)
|
||||
faraday-excon (1.1.0)
|
||||
faraday-net_http (1.0.1)
|
||||
faraday-net_http_persistent (1.1.0)
|
||||
ffi (1.15.1)
|
||||
forwardable-extended (2.6.0)
|
||||
gemoji (3.0.1)
|
||||
github-pages (215)
|
||||
github-pages-health-check (= 1.17.2)
|
||||
jekyll (= 3.9.0)
|
||||
jekyll-avatar (= 0.7.0)
|
||||
jekyll-coffeescript (= 1.1.1)
|
||||
jekyll-commonmark-ghpages (= 0.1.6)
|
||||
jekyll-default-layout (= 0.1.4)
|
||||
jekyll-feed (= 0.15.1)
|
||||
jekyll-gist (= 1.5.0)
|
||||
jekyll-github-metadata (= 2.13.0)
|
||||
jekyll-mentions (= 1.6.0)
|
||||
jekyll-optional-front-matter (= 0.3.2)
|
||||
jekyll-paginate (= 1.1.0)
|
||||
jekyll-readme-index (= 0.3.0)
|
||||
jekyll-redirect-from (= 0.16.0)
|
||||
jekyll-relative-links (= 0.6.1)
|
||||
jekyll-remote-theme (= 0.4.3)
|
||||
jekyll-sass-converter (= 1.5.2)
|
||||
jekyll-seo-tag (= 2.7.1)
|
||||
jekyll-sitemap (= 1.4.0)
|
||||
jekyll-swiss (= 1.0.0)
|
||||
jekyll-theme-architect (= 0.1.1)
|
||||
jekyll-theme-cayman (= 0.1.1)
|
||||
jekyll-theme-dinky (= 0.1.1)
|
||||
jekyll-theme-hacker (= 0.1.2)
|
||||
jekyll-theme-leap-day (= 0.1.1)
|
||||
jekyll-theme-merlot (= 0.1.1)
|
||||
jekyll-theme-midnight (= 0.1.1)
|
||||
jekyll-theme-minimal (= 0.1.1)
|
||||
jekyll-theme-modernist (= 0.1.1)
|
||||
jekyll-theme-primer (= 0.5.4)
|
||||
jekyll-theme-slate (= 0.1.1)
|
||||
jekyll-theme-tactile (= 0.1.1)
|
||||
jekyll-theme-time-machine (= 0.1.1)
|
||||
jekyll-titles-from-headings (= 0.5.3)
|
||||
jemoji (= 0.12.0)
|
||||
kramdown (= 2.3.1)
|
||||
kramdown-parser-gfm (= 1.1.0)
|
||||
liquid (= 4.0.3)
|
||||
mercenary (~> 0.3)
|
||||
minima (= 2.5.1)
|
||||
nokogiri (>= 1.10.4, < 2.0)
|
||||
rouge (= 3.26.0)
|
||||
terminal-table (~> 1.4)
|
||||
github-pages-health-check (1.17.2)
|
||||
addressable (~> 2.3)
|
||||
dnsruby (~> 1.60)
|
||||
octokit (~> 4.0)
|
||||
public_suffix (>= 2.0.2, < 5.0)
|
||||
typhoeus (~> 1.3)
|
||||
html-pipeline (2.14.0)
|
||||
activesupport (>= 2)
|
||||
nokogiri (>= 1.4)
|
||||
http_parser.rb (0.6.0)
|
||||
i18n (0.9.5)
|
||||
concurrent-ruby (~> 1.0)
|
||||
jekyll (3.9.0)
|
||||
addressable (~> 2.4)
|
||||
colorator (~> 1.0)
|
||||
em-websocket (~> 0.5)
|
||||
i18n (~> 0.7)
|
||||
jekyll-sass-converter (~> 1.0)
|
||||
jekyll-watch (~> 2.0)
|
||||
kramdown (>= 1.17, < 3)
|
||||
liquid (~> 4.0)
|
||||
mercenary (~> 0.3.3)
|
||||
pathutil (~> 0.9)
|
||||
rouge (>= 1.7, < 4)
|
||||
safe_yaml (~> 1.0)
|
||||
jekyll-avatar (0.7.0)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
jekyll-coffeescript (1.1.1)
|
||||
coffee-script (~> 2.2)
|
||||
coffee-script-source (~> 1.11.1)
|
||||
jekyll-commonmark (1.3.1)
|
||||
commonmarker (~> 0.14)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-commonmark-ghpages (0.1.6)
|
||||
commonmarker (~> 0.17.6)
|
||||
jekyll-commonmark (~> 1.2)
|
||||
rouge (>= 2.0, < 4.0)
|
||||
jekyll-default-layout (0.1.4)
|
||||
jekyll (~> 3.0)
|
||||
jekyll-feed (0.15.1)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-gist (1.5.0)
|
||||
octokit (~> 4.2)
|
||||
jekyll-github-metadata (2.13.0)
|
||||
jekyll (>= 3.4, < 5.0)
|
||||
octokit (~> 4.0, != 4.4.0)
|
||||
jekyll-mentions (1.6.0)
|
||||
html-pipeline (~> 2.3)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-optional-front-matter (0.3.2)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
jekyll-paginate (1.1.0)
|
||||
jekyll-readme-index (0.3.0)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
jekyll-redirect-from (0.16.0)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-relative-links (0.6.1)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-remote-theme (0.4.3)
|
||||
addressable (~> 2.0)
|
||||
jekyll (>= 3.5, < 5.0)
|
||||
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
|
||||
rubyzip (>= 1.3.0, < 3.0)
|
||||
jekyll-sass-converter (1.5.2)
|
||||
sass (~> 3.4)
|
||||
jekyll-seo-tag (2.7.1)
|
||||
jekyll (>= 3.8, < 5.0)
|
||||
jekyll-sitemap (1.4.0)
|
||||
jekyll (>= 3.7, < 5.0)
|
||||
jekyll-swiss (1.0.0)
|
||||
jekyll-theme-architect (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-cayman (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-dinky (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-hacker (0.1.2)
|
||||
jekyll (> 3.5, < 5.0)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-leap-day (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-merlot (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-midnight (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-minimal (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-modernist (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-primer (0.5.4)
|
||||
jekyll (> 3.5, < 5.0)
|
||||
jekyll-github-metadata (~> 2.9)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-slate (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-tactile (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-theme-time-machine (0.1.1)
|
||||
jekyll (~> 3.5)
|
||||
jekyll-seo-tag (~> 2.0)
|
||||
jekyll-titles-from-headings (0.5.3)
|
||||
jekyll (>= 3.3, < 5.0)
|
||||
jekyll-watch (2.2.1)
|
||||
listen (~> 3.0)
|
||||
jemoji (0.12.0)
|
||||
gemoji (~> 3.0)
|
||||
html-pipeline (~> 2.2)
|
||||
jekyll (>= 3.0, < 5.0)
|
||||
kramdown (2.3.1)
|
||||
rexml
|
||||
kramdown-parser-gfm (1.1.0)
|
||||
kramdown (~> 2.0)
|
||||
liquid (4.0.3)
|
||||
listen (3.5.1)
|
||||
rb-fsevent (~> 0.10, >= 0.10.3)
|
||||
rb-inotify (~> 0.9, >= 0.9.10)
|
||||
mercenary (0.3.6)
|
||||
mini_portile2 (2.5.2)
|
||||
net-ftp (~> 0.1)
|
||||
minima (2.5.1)
|
||||
jekyll (>= 3.5, < 5.0)
|
||||
jekyll-feed (~> 0.9)
|
||||
jekyll-seo-tag (~> 2.1)
|
||||
minitest (5.14.4)
|
||||
multipart-post (2.1.1)
|
||||
net-ftp (0.1.2)
|
||||
net-protocol
|
||||
time
|
||||
net-protocol (0.1.0)
|
||||
nokogiri (1.11.6)
|
||||
mini_portile2 (~> 2.5.0)
|
||||
racc (~> 1.4)
|
||||
nokogiri (1.11.6-x86_64-linux)
|
||||
racc (~> 1.4)
|
||||
octokit (4.21.0)
|
||||
faraday (>= 0.9)
|
||||
sawyer (~> 0.8.0, >= 0.5.3)
|
||||
pathutil (0.16.2)
|
||||
forwardable-extended (~> 2.6)
|
||||
public_suffix (4.0.6)
|
||||
racc (1.5.2)
|
||||
rb-fsevent (0.11.0)
|
||||
rb-inotify (0.10.1)
|
||||
ffi (~> 1.0)
|
||||
rexml (3.2.5)
|
||||
rouge (3.26.0)
|
||||
ruby-enum (0.9.0)
|
||||
i18n
|
||||
ruby2_keywords (0.0.4)
|
||||
rubyzip (2.3.0)
|
||||
safe_yaml (1.0.5)
|
||||
sass (3.7.4)
|
||||
sass-listen (~> 4.0.0)
|
||||
sass-listen (4.0.0)
|
||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
||||
rb-inotify (~> 0.9, >= 0.9.7)
|
||||
sawyer (0.8.2)
|
||||
addressable (>= 2.3.5)
|
||||
faraday (> 0.8, < 2.0)
|
||||
simpleidn (0.2.1)
|
||||
unf (~> 0.1.4)
|
||||
terminal-table (1.8.0)
|
||||
unicode-display_width (~> 1.1, >= 1.1.1)
|
||||
thread_safe (0.3.6)
|
||||
time (0.1.0)
|
||||
typhoeus (1.4.0)
|
||||
ethon (>= 0.9.0)
|
||||
tzinfo (1.2.9)
|
||||
thread_safe (~> 0.1)
|
||||
unf (0.1.4)
|
||||
unf_ext
|
||||
unf_ext (0.0.7.7)
|
||||
unicode-display_width (1.7.0)
|
||||
zeitwerk (2.4.2)
|
||||
|
||||
PLATFORMS
|
||||
aarch64-linux
|
||||
x86_64-linux
|
||||
|
||||
DEPENDENCIES
|
||||
github-pages
|
||||
jekyll-redirect-from
|
||||
|
||||
BUNDLED WITH
|
||||
2.2.18
|
||||
@@ -1,8 +0,0 @@
|
||||
theme: jekyll-theme-minimal
|
||||
exclude: [ruby-bundle, vendor]
|
||||
plugins:
|
||||
- jekyll-redirect-from
|
||||
google_analytics: UA-93396600-3
|
||||
collections:
|
||||
api:
|
||||
output: true
|
||||
@@ -1,72 +0,0 @@
|
||||
|
||||
# This data could theoretically be retrieved directly from the md files:
|
||||
# https://jekyllrb.com/tutorials/navigation/#scenario-8-retrieving-items-based-on-front-matter-properties
|
||||
|
||||
sections:
|
||||
- title: General
|
||||
docs:
|
||||
- title: Getting Started
|
||||
url: /
|
||||
- title: ODrive Tool
|
||||
url: /odrivetool
|
||||
- title: Control Modes
|
||||
url: /control-modes
|
||||
- title: Parameters & Commands
|
||||
url: /commands
|
||||
- title: Encoders
|
||||
url: /encoders
|
||||
- title: Control Structure & Tuning
|
||||
url: /control
|
||||
- title: Troubleshooting
|
||||
url: /troubleshooting
|
||||
- title: Specifications
|
||||
url: /specifications
|
||||
- title: Ground Loops
|
||||
url: /ground-loops
|
||||
- title: Tutorials
|
||||
docs:
|
||||
- title: Hoverboard Guide
|
||||
url: /hoverboard
|
||||
- title: Migration Guide
|
||||
url: /migration
|
||||
- title: CAN Guide
|
||||
url: /can-guide
|
||||
- title: Interfaces & Protocols
|
||||
docs:
|
||||
- title: Pinout
|
||||
url: /pinout
|
||||
- title: USB
|
||||
url: /usb
|
||||
- title: UART
|
||||
url: /uart
|
||||
- title: Native Protocol
|
||||
url: /native-protocol
|
||||
- title: ASCII Protocol
|
||||
url: /ascii-protocol
|
||||
- title: CAN Protocol
|
||||
url: /can-protocol
|
||||
- title: Step & Direction
|
||||
url: /step-direction
|
||||
- title: RC PWM
|
||||
url: /rc-pwm
|
||||
- title: Analog Input
|
||||
url: /analog-input
|
||||
- title: Homing & Endstops
|
||||
url: /endstops
|
||||
- title: Thermistors
|
||||
url: /thermistors
|
||||
- title: API Reference
|
||||
- title: For ODrive Developers
|
||||
docs:
|
||||
- title: Firmware Developer Guide
|
||||
url: /developer-guide
|
||||
- title: Configuring Visual Studio Code
|
||||
url: /configuring-vscode
|
||||
- title: Configuring Eclipse
|
||||
url: /configuring-eclipse
|
||||
- title: Component Guides
|
||||
docs:
|
||||
- title: Motor Guide
|
||||
url: https://docs.google.com/spreadsheets/d/12vzz7XVEK6YNIOqH0jAz51F5VUpc-lJEs3mmkWP1H4Y
|
||||
- title: Encoder Guide
|
||||
url: https://docs.google.com/spreadsheets/d/1OBDwYrBb5zUPZLrhL98ezZbg94tUsZcdTuwiVNgVqpU
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
title: '[% if interface %][[interface.fullname]][% else %][[enum.fullname]][% endif %]'
|
||||
layout: default
|
||||
edit_url: 'Firmware/odrive-interface.yaml'
|
||||
download:
|
||||
url: 'Firmware/odrive-interface.yaml'
|
||||
text: 'download as YAML'
|
||||
---
|
||||
|
||||
[% set attr_lookup_table =
|
||||
{
|
||||
'ODrive': '<odrv>',
|
||||
'ODrive.Axis': '<odrv>.<axis>',
|
||||
'ODrive.Motor': '<odrv>.<axis>.motor',
|
||||
}
|
||||
%]
|
||||
|
||||
[%- macro interface_ref(type) -%]
|
||||
**[['[']]<span [% if type.brief %]title="[[type.brief]]"[% endif %]>[[type.name]]</span>[[']']]([[type.fullname | lower]])**
|
||||
[%- endmacro %]
|
||||
|
||||
[%- macro value_type_ref(type) -%]
|
||||
[%- if type.builtin -%]
|
||||
<span title="C type: [[type.c_name]], Python type: [[type.py_type]]">[[type.name]]</span>
|
||||
[%- else -%]
|
||||
[['[']]<span [% if type.brief %]title="[[type.brief]]"[% endif %]>[[type.name]]</span>[[']']]([[type.fullname | lower]])
|
||||
[%- endif %]
|
||||
[%- endmacro %]
|
||||
|
||||
[% macro attr_ref(token, scope, intf, attr) -%]
|
||||
**[['[']]<span [% if attr.brief %]title="[[attr.brief]]"[% endif %]>[% if intf != scope %][[attr_lookup_table[intf.fullname] | html_escape]].[% endif %][[token]]</span>[[']']]([[attr.parent.fullname | lower]]#[[attr.name]])**
|
||||
[%- endmacro %]
|
||||
|
||||
[% if interface %]
|
||||
[% set scope = interface %]
|
||||
[% else %]
|
||||
[% set scope = enum.parent %]
|
||||
[% endif %]
|
||||
|
||||
[%- macro doc_tokenize(text) %][[ text | tokenize(scope, interface_ref, value_type_ref, attr_ref) ]][% endmacro %]
|
||||
|
||||
[%- macro status_badge(status) %]
|
||||
[%- if status == 'experimental' %]
|
||||
<span style="border: 1px solid; border-radius: 3px; padding: 1px 10px; color: #c35400; float: right;" title="This feature is still experimental. It may be buggy or change later. Use with caution.">Experimental</span>
|
||||
[%- endif %]
|
||||
[%- if status == 'deprecated' %]
|
||||
<span style="border: 1px solid; border-radius: 3px; padding: 1px 10px; color: #c35400; float: right;" title="This feature is deprecated and may be removed in future versions.">Deprecated</span>
|
||||
[%- endif %]
|
||||
[%- endmacro %]
|
||||
|
||||
[%- macro breadcrumbs(title) %]
|
||||
# [% for item in title.split('.') | diagonalize -%]
|
||||
<a href="[[item | join('.') | lower]]">[[item[-1]]]</a>
|
||||
[%- if not loop.last %]<span style="font-size: x-large;opacity: 50%;"> 〉</span>[% endif %]
|
||||
[%- endfor %]
|
||||
[%- endmacro %]
|
||||
|
||||
[% if interface %]
|
||||
|
||||
[[breadcrumbs(interface.fullname)]]
|
||||
|
||||
[%- if interface.doc or interface.brief %]
|
||||
[[doc_tokenize(interface.brief)]][% if interface.brief and interface.doc %]
|
||||
|
||||
[% endif %][[doc_tokenize(interface.doc)]]
|
||||
[%- endif %]
|
||||
|
||||
## Attributes
|
||||
|
||||
[% if interface.attributes %]
|
||||
[% for attr in interface.attributes.values() %]
|
||||
[%- if attr.type.purename == 'fibre.Property' %]
|
||||
<a name="[[attr.name]]"></a><span style="font-size: medium;">**<code markdown="span">[[attr.name]]</code>** — <code markdown="span">[[value_type_ref(attr.type.value_type)]]</code></span> <span style="font-size: small;">_[[attr.type.mode]]_</span>
|
||||
[%- else %]
|
||||
<a name="[[attr.name]]"></a><span style="font-size: medium;">**<code markdown="span">[[attr.name]]</code>** — <code markdown="span">[[interface_ref(attr.type)]]</code></span>
|
||||
[%- endif %]
|
||||
[[-status_badge(attr.status)]]
|
||||
|
||||
<ul markdown="block">
|
||||
[% if attr.doc or attr.brief %]
|
||||
[[doc_tokenize(attr.brief)]][% if attr.brief and attr.doc %]
|
||||
|
||||
[% endif %][%- if attr.unit %]
|
||||
|
||||
**Unit:** [[attr.unit]]
|
||||
|
||||
[% endif %][[doc_tokenize(attr.doc)]]
|
||||
[%- else %]
|
||||
_No description_
|
||||
[%- endif %]
|
||||
</ul>
|
||||
[% endfor %]
|
||||
[% else %]
|
||||
This interface has no attributes.
|
||||
[% endif %]
|
||||
|
||||
## Functions
|
||||
|
||||
[% if interface.functions %]
|
||||
[% for function in interface.functions.values() %]
|
||||
<a name="[[function.name]]"></a><span style="font-size: medium;"><code markdown="span">**[[function.name]]**([% for arg in function.in.values() | skip_first %][[arg.name]]: [[value_type_ref(arg.type)]][[', ' if not loop.last]][% endfor %])</code>[% if function.out %] ➔ <code markdown="span">[% for arg in function.out.values() %][[arg.name]]: [[value_type_ref(arg.type)]][[', ' if not loop.last]][% endfor %]</code>[% endif %]</span>
|
||||
|
||||
<ul markdown="block">
|
||||
[% if function.doc or function.brief %]
|
||||
[[doc_tokenize(function.brief)]][% if function.brief and function.doc %]
|
||||
|
||||
[% endif %][[doc_tokenize(function.doc)]]
|
||||
[%- else %]
|
||||
_No description_
|
||||
[%- endif %]
|
||||
[% if function.in.values() | skip_first %]
|
||||
**Inputs:**
|
||||
[%- for arg in function.in.values() | skip_first %]
|
||||
- `[[arg.name]]`: [% if arg.doc %][[doc_tokenize(arg.doc)]][% else %] _No description_[% endif %]
|
||||
[%- endfor %]
|
||||
[%- endif %]
|
||||
[% if function.out.values() %]
|
||||
**Outputs:**
|
||||
[%- for arg in function.out.values() %]
|
||||
- `[[arg.name]]`: [% if arg.doc %][[doc_tokenize(arg.doc)]][% else %] _No description_[% endif %]
|
||||
[%- endfor %]
|
||||
[%- endif %]
|
||||
</ul>
|
||||
[% endfor %]
|
||||
[% else %]
|
||||
This interface has no functions.
|
||||
[% endif %]
|
||||
|
||||
[% else %]
|
||||
|
||||
[[breadcrumbs(enum.fullname)]]
|
||||
|
||||
[%- if enum.doc or enum.brief %]
|
||||
[[doc_tokenize(enum.brief)]][% if enum.brief and enum.doc %]
|
||||
|
||||
[% endif %][[doc_tokenize(enum.doc)]]
|
||||
[%- endif %]
|
||||
|
||||
## [% if enum.is_flags %]Flags[% else %]Values[% endif %]
|
||||
|
||||
[% for k, value in enum['values'].items() %]
|
||||
<a name="[[value.name]]"></a><span style="font-size: medium;">**<code markdown="span">[[enum.name | to_macro_case]]_[[value.name]]</code>** — [% if enum.is_flags %]0x[['%08x' | format(value.value)]][% else %][[value.value]][% endif %]</span>
|
||||
[[-status_badge(value.status)]]
|
||||
|
||||
<ul markdown="block">
|
||||
[% if value.doc or value.brief %]
|
||||
[[doc_tokenize(value.brief)]][% if value.brief and value.doc %]
|
||||
|
||||
[% endif %][[doc_tokenize(value.doc)]]
|
||||
[%- else %]
|
||||
_No description_
|
||||
[%- endif %]
|
||||
</ul>
|
||||
[% endfor %]
|
||||
|
||||
[% endif %]
|
||||
@@ -1,41 +0,0 @@
|
||||
[%- macro dump_interfaces(interfaces, level) %]
|
||||
[%- for intf in interfaces %]
|
||||
[%- if intf.interfaces or intf.value_types %]
|
||||
<li>
|
||||
{% assign myvar = (page.title + '.') | split: "[[intf.fullname + '.']]" %}
|
||||
<input id="chk-[[intf.fullname]]" type="checkbox" {% if myvar[0] == "" %}checked{% endif %} hidden />
|
||||
<p class="navitem{% if page.title == "[[intf.fullname]]" %} currentitem{% endif %}">
|
||||
[% for i in range(level) %]<a class="levelbar"> </a>[% endfor %]
|
||||
<label style="margin-left: [[level*0]]px;" for="chk-[[intf.fullname]]" class="chevron"></label>
|
||||
<a href="{{site.baseurl}}/api/[[intf.fullname | lower]]">[[intf.name]]</a>
|
||||
</p>
|
||||
<ul class="expandable-list">
|
||||
[[dump_interfaces(intf.interfaces, level + 1) | indent(4)]]
|
||||
[[dump_value_types(intf.enums, level + 1) | indent(4)]]
|
||||
</ul>
|
||||
</li>
|
||||
[%- else %]
|
||||
<li>
|
||||
<p class="navitem{% if page.title == "[[intf.fullname]]" %} currentitem{% endif %}">
|
||||
[% for i in range(level) %]<a class="levelbar"> </a>[% endfor %]
|
||||
<span style="margin-left: 7px; margin-right: 10px; float: inline-start;">•</span>
|
||||
<a href="{{site.baseurl}}/api/[[intf.fullname | lower]]">[[intf.name]]</a>
|
||||
</p>
|
||||
</li>
|
||||
[%- endif %]
|
||||
[%- endfor %]
|
||||
[%- endmacro %]
|
||||
|
||||
[%- macro dump_value_types(value_types, level) %]
|
||||
[%- for enum in value_types %]
|
||||
<li>
|
||||
<p class="navitem{% if page.title == "[[enum.fullname]]" %} currentitem{% endif %}">
|
||||
[% for i in range(level) %]<a class="levelbar"> </a>[% endfor %]
|
||||
<span style="margin-left: 7px; margin-right: 10px; float: inline-start;">•</span>
|
||||
<a href="{{site.baseurl}}/api/[[enum.fullname | lower]]">[[enum.name]]</a>
|
||||
</p>
|
||||
</li>
|
||||
[%- endfor %]
|
||||
[%- endmacro %]
|
||||
|
||||
[[dump_interfaces(toplevel_interfaces, 0)]]
|
||||
@@ -1,142 +0,0 @@
|
||||
{% assign pagename = page.url | replace_first: '/', '' | replace: '.html', '' %}
|
||||
{% if pagename == '' %}{% assign pagename = 'getting-started' %}{% endif %}
|
||||
|
||||
<!DOCTYPE html>
|
||||
<!-- source: https://github.com/pages-themes/minimal/blob/master/_layouts/default.html -->
|
||||
<html lang="{{ site.lang | default: "en-US" }}">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
|
||||
{% seo %}
|
||||
<link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
|
||||
<!--[if lt IE 9]>
|
||||
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
</head>
|
||||
<body>
|
||||
<div class="wrapper">
|
||||
<header>
|
||||
<div>
|
||||
<h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repository_name }} Documentation</a></h1>
|
||||
|
||||
{% if site.logo %}
|
||||
<img src="{{site.logo | relative_url}}" alt="Logo" />
|
||||
{% endif %}
|
||||
|
||||
<p>{{ site.description | default: site.github.project_tagline }}</p>
|
||||
</div>
|
||||
<div style="overflow-y: auto;">
|
||||
<ul id="navbar">
|
||||
{% for section in site.data.index.sections %}
|
||||
<li class="navgroup">
|
||||
<p class="navheader">{{ section.title }}</p>
|
||||
<ul>
|
||||
{% if section.title != "API Reference" %}
|
||||
{% for item in section.docs %}
|
||||
{% assign prefix = item.url | slice: 0 %}
|
||||
{% assign itemname = item.url | replace_first: '/', '' | replace: '.html', '' %}
|
||||
{% if itemname == '' %}{% assign itemname = 'getting-started' %}{% endif %}
|
||||
<li><a class="navitem{% if pagename == itemname %} currentitem{% endif %}" href="{% if prefix == '/' %}{{ site.baseurl }}{% endif %}{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
|
||||
{% endfor %}
|
||||
{% else %}
|
||||
{% include apiindex.html %}
|
||||
{% endif %}
|
||||
</ul>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
<div style="margin-top: 10px;">
|
||||
{% if site.github.is_project_page %}
|
||||
<p class="view"><a href="{{ site.github.repository_url }}">View the Project on GitHub <small>{{ site.github.repository_nwo }}</small></a></p>
|
||||
{% endif %}
|
||||
|
||||
{% if site.github.is_user_page %}
|
||||
<p class="view"><a href="{{ site.github.owner_url }}">View My GitHub Profile</a></p>
|
||||
{% endif %}
|
||||
|
||||
<p>Help improve these docs: submit edits using the link in the top right.</p>
|
||||
<p>If you need help, please search or ask the <a href=https://discourse.odriverobotics.com>ODrive Community</a>.</p>
|
||||
|
||||
{% if site.show_downloads %}
|
||||
<ul>
|
||||
<li><a href="{{ site.github.zip_url }}">Download <strong>ZIP File</strong></a></li>
|
||||
<li><a href="{{ site.github.tar_url }}">Download <strong>TAR Ball</strong></a></li>
|
||||
<li><a href="{{ site.github.repository_url }}">View On <strong>GitHub</strong></a></li>
|
||||
</ul>
|
||||
{% endif %}
|
||||
</div>
|
||||
</header>
|
||||
<section>
|
||||
|
||||
<div class="pageactions">
|
||||
<div>
|
||||
<!-- edit icon taken from GitHub -->
|
||||
<svg transform="translate(0,1)" class="octicon octicon-pencil" viewBox="0 0 14 16" version="1.1" width="10" height="12" aria-hidden="true">
|
||||
<path fill-rule="evenodd" d="M0 12v3h3l8-8-3-3-8 8zm3 2H1v-2h1v1h1v1zm10.3-9.3L12 6 9 3l1.3-1.3a.996.996 0 0 1 1.41 0l1.59 1.59c.39.39.39 1.02 0 1.41z"></path>
|
||||
</svg>
|
||||
{% if page.edit_url %}
|
||||
{% assign edit_url = "https://www.github.com/madcowswe/ODrive/edit/master/" | append: page.edit_url %}
|
||||
{% else %}
|
||||
{% assign edit_url = "https://www.github.com/madcowswe/ODrive/edit/master/docs/" | append: pagename | append: ".md" %}
|
||||
{% endif %}
|
||||
<a href="{{edit_url}}">edit on GitHub</a>
|
||||
</div>
|
||||
|
||||
{% if page.download %}
|
||||
<div>
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="10" height="10" style="fill: #656565;">
|
||||
<path d="M216 0h80c13.3 0 24 10.7 24 24v168h87.7c17.8 0 26.7 21.5 14.1 34.1L269.7 378.3c-7.5 7.5-19.8 7.5-27.3 0L90.1 226.1c-12.6-12.6-3.7-34.1 14.1-34.1H192V24c0-13.3 10.7-24 24-24zm296 376v112c0 13.3-10.7 24-24 24H24c-13.3 0-24-10.7-24-24V376c0-13.3 10.7-24 24-24h146.7l49 49c20.1 20.1 52.5 20.1 72.6 0l49-49H488c13.3 0 24 10.7 24 24zm-124 88c0-11-9-20-20-20s-20 9-20 20 9 20 20 20 20-9 20-20zm64 0c0-11-9-20-20-20s-20 9-20 20 9 20 20 20 20-9 20-20z"/>
|
||||
</svg>
|
||||
<a href="https://www.github.com/madcowswe/ODrive/blob/master/{{page.download.url}}">{{page.download.text}}</a>
|
||||
</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
|
||||
|
||||
{{ content }}
|
||||
|
||||
</section>
|
||||
<!--<footer>
|
||||
{% if site.github.is_project_page %}
|
||||
<p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
|
||||
{% endif %}
|
||||
<p><small>Hosted on GitHub Pages — Theme by <a href="https://github.com/orderedlist">orderedlist</a></small></p>
|
||||
</footer>-->
|
||||
</div>
|
||||
<script src="{{ "/assets/js/scale.fix.js" | relative_url }}"></script>
|
||||
{% if site.google_analytics %}
|
||||
<script>
|
||||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||||
ga('create', '{{ site.google_analytics }}', 'auto');
|
||||
ga('send', 'pageview');
|
||||
</script>
|
||||
{% endif %}
|
||||
<script type="text/javascript">
|
||||
// Rewrite all links that start with "../" to point to the GitHub repo
|
||||
window.onload = function(){
|
||||
var links = document.links;
|
||||
var i = links.length;
|
||||
while (i--) {
|
||||
if (links[i].getAttribute("href").slice(0, 3) == "../") {
|
||||
links[i].href = "https://github.com/madcowswe/ODrive/blob/master/" + links[i].getAttribute("href").slice(3);
|
||||
}
|
||||
if (links[i].getAttribute("href").slice(0, 15) == "getting-started") {
|
||||
links[i].href = "/" + links[i].getAttribute("href").slice(15);
|
||||
}
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<script>
|
||||
// Scroll the navbar to the position of the selected item
|
||||
var element = document.getElementsByClassName("currentitem")[0];
|
||||
element.scrollIntoView(false);
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# Analog Input
|
||||
|
||||
Analog inputs can be used to measure voltages between 0 and 3.3V. ODrive uses a 12 bit ADC (4096 steps) and so has a maximum resolution of 0.8 mV. A GPIO must be configured with `<odrv>.config.gpioX_mode = GPIO_MODE_ANALOG_IN` before it can be used as an analog input. To read the voltage on GPIO1 in odrivetool the following would be entered: `odrv0.get_adc_voltage(1)`.
|
||||
|
||||
Similar to RC PWM input, analog inputs can also be used to feed any of the numerical properties that are visible in `odrivetool`. This is done by configuring `odrv0.config.gpio3_analog_mapping` and `odrv0.config.gpio4_analog_mapping`. Refer to [RC PWM](rc-pwm) for instructions on how to configure the mappings.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Anti-cogging
|
||||
|
||||
ODrive supports an anti-cogging algorithm that attempts to compensate for the rather high cogging torques seen in hobby motors.
|
||||
|
||||
`<odrv>.<axis>.controller.config.anticogging` is a configuration structure that contains the following items:
|
||||
|
||||
Name | Type | Use
|
||||
-- | -- | --
|
||||
index | uint32 | The current position being used for calibration
|
||||
pre_calibrated | bool | If true and using index or absolute encoder, load anticogging map from NVM at startup
|
||||
calib_anticogging | bool | True when calibration is ongoing
|
||||
calib_pos_threshold | float32 | (pos_estimate - index) must be < this value to calibrate. Larger values speed up calibration but hurt accuracy
|
||||
calib_vel_threshold | float32 | (vel_estimate) must be < this value to calibrate. Larger values speed up calibration but hurt accuracy.
|
||||
cogging_ratio | float32 | Deprecated
|
||||
anticogging_enabled | bool | Enable or disable anticogging. A valid anticogging map can be ignored by setting this to `false`
|
||||
|
||||
## Calibration
|
||||
|
||||
To calibrate anticogging, first make sure you can adequately control the motor. It should respond to position commands.
|
||||
|
||||
Start by putting the axis in `AXIS_STATE_CLOSED_LOOP_CONTROL` with `CONTROL_MODE_POSITION_CONTROL` and `INPUT_MODE_PASSTHROUGH`. Make sure you have good control of the motor in this state (it responds to position commands). Now, tune the motor to be very stiff - high `pos_gain` and relatively high `vel_integrator_gain`. This will help in calibration.
|
||||
|
||||
Run `controller.start_anticogging_calibration()`. The motor will start turning slowly, calibrating each point. If you like, you can start a liveplotter session before running this command so that you can watch the position move.
|
||||
|
||||
Once it's complete (it should take about 1 minute), the motor will return to 0 and the value `controller.anticogging_valid` should report True. If `controller.config.anticogging.anticogging_enabled` == True, anticogging will now be running on this axis.
|
||||
|
||||
## Saving to NVM
|
||||
|
||||
As of v0.5.1, the anticogging map is saved to NVM after calibrating and calling `odrv0.save_configuration()`
|
||||
|
||||
The anticogging map can be reloaded automatically at startup by setting `controller.config.anticogging.pre_calibrated = True` and saving the configuration. However, this map is only valid and will only be loaded for absolute encoders, or encoders with index pins after the index search.
|
||||
|
||||
## Example
|
||||
|
||||
``` Py
|
||||
odrv0.axis0.encoder.config.use_index = True
|
||||
odrv0.axis0.requested_state = AXIS_STATE_FULL_CALIBRATION_SEQUENCE
|
||||
odrv0.axis0.encoder.config.pre_calibrated = True
|
||||
odrv0.axis0.motor.config.pre_calibrated = True
|
||||
|
||||
odrv0.axis0.controller.config.control_mode = CONTROL_MODE_POSITION_CONTROL
|
||||
odrv0.axis0.controller.config.input_mode = INPUT_MODE_PASSTHROUGH
|
||||
odrv0.axis0.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL
|
||||
|
||||
odrv0.axis0.controller.start_anticogging_calibration()
|
||||
|
||||
# Wait until controller.config.anticogging.calib_anticogging == False
|
||||
|
||||
odrv0.axis0.controller.config.anticogging.pre_calibrated = True
|
||||
|
||||
odrv0.save_configuration()
|
||||
odrv0.reboot()
|
||||
```
|
||||
@@ -1,145 +0,0 @@
|
||||
|
||||
# ASCII Protocol
|
||||
|
||||
## How to send commands
|
||||
|
||||
* **Via USB:**
|
||||
* **Windows:** Use [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/) to manually send commands or open the COM port using your favorite programming language
|
||||
* **Linux/macOS:** Run `/dev/tty*` to list all serial ports. The ODrive will show up as `/dev/ttyACM0` (or similar) on Linux and `/dev/tty.usbmodem[...]` on macOS. Once you know the name, you can use `screen /dev/ttyACM0` (with the correct name) to send commands manually or open the device using your favorite programming language. Serial ports on Unix can be opened, written to and read from like a normal file.
|
||||
* **Via UART:** Connect the ODrive's TX (GPIO1) to your host's RX. Connect your ODrive's RX (GPIO2) to your host's TX. See [UART](uart) for more info.
|
||||
* **Arduino:** You can use the [ODrive Arduino library](https://github.com/madcowswe/ODrive/tree/master/Arduino/ODriveArduino) to talk to the ODrive.
|
||||
* **Windows/Linux/macOS:** You can use an FTDI USB-UART cable to connect to the ODrive.
|
||||
|
||||
The ODrive does not echo commands. That means that when you type commands into a program like `screen`, the characters you type won't show up in the console.
|
||||
|
||||
### Arduino
|
||||
There is an Arduino library that gives some examples on how to use the ASCII protocol to communicate with the ODrive. Check it out [here](../Arduino/ODriveArduino).
|
||||
|
||||
## Command format
|
||||
|
||||
The ASCII protocol is human-readable and line-oriented, with each line having the following format:
|
||||
|
||||
```
|
||||
command *42 ; comment [new line character]
|
||||
```
|
||||
|
||||
* `*42` stands for a GCode compatible checksum and can be omitted. If and only if a checksum is provided, the device will also include a checksum in the response, if any. If the checksum is provided but is not valid, the line is ignored. The checksum is calculated as the bitwise xor of all characters before the asterisk (`*`). <br> Example of a valid checksum: `r vbus_voltage *93`.
|
||||
* comments are supported for GCode compatibility
|
||||
* the command is interpreted once the new-line character is encountered
|
||||
|
||||
## Command Reference
|
||||
|
||||
#### Motor trajectory command
|
||||
```
|
||||
t motor destination
|
||||
```
|
||||
* `t` for trajectory
|
||||
* `motor` is the motor number, `0` or `1`.
|
||||
* `destination` is the goal position, in [turns].
|
||||
|
||||
Example: `t 0 -2`
|
||||
|
||||
For general moving around of the axis, this is the recommended command.
|
||||
|
||||
This command updates the watchdog timer for the motor.
|
||||
|
||||
#### Motor Position command
|
||||
For basic use where you send one setpoint at at a time, use the `q` command.
|
||||
If you have a realtime controller that is streaming setpoints and tracking a trajectory, use the `p` command.
|
||||
|
||||
```
|
||||
q motor position velocity_lim torque_lim
|
||||
```
|
||||
* `q` for position
|
||||
* `motor` is the motor number, `0` or `1`.
|
||||
* `position` is the desired position, in [turns].
|
||||
* `velocity_lim` is the velocity limit, in [turns/s] (optional).
|
||||
* `torque_lim` is the torque limit, in [Nm] (optional).
|
||||
|
||||
Example: `q 0 -2 1 0.1`
|
||||
|
||||
```
|
||||
p motor position velocity_ff torque_ff
|
||||
```
|
||||
* `p` for position
|
||||
* `motor` is the motor number, `0` or `1`.
|
||||
* `position` is the desired position, in [turns].
|
||||
* `velocity_ff` is the velocity feed-forward term, in [turns/s] (optional).
|
||||
* `torque_ff` is the torque feed-forward term, in [Nm] (optional).
|
||||
|
||||
Example: `p 0 -2 0 0`
|
||||
|
||||
Note that if you don't know what feed-forward is or what it's used for, simply omit it.
|
||||
|
||||
This command updates the watchdog timer for the motor.
|
||||
|
||||
#### Motor Velocity command
|
||||
```
|
||||
v motor velocity torque_ff
|
||||
```
|
||||
* `v` for velocity
|
||||
* `motor` is the motor number, `0` or `1`.
|
||||
* `velocity` is the desired velocity in [turns/s].
|
||||
* `torque_ff` is the torque feed-forward term, in [Nm] (optional).
|
||||
|
||||
Example: `v 0 1 0`
|
||||
|
||||
Note that if you don't know what feed-forward is or what it's used for, simply omit it.
|
||||
|
||||
This command updates the watchdog timer for the motor.
|
||||
|
||||
#### Motor Current command
|
||||
```
|
||||
c motor torque
|
||||
```
|
||||
* `c` for torque
|
||||
* `motor` is the motor number, `0` or `1`.
|
||||
* `torque` is the desired torque in [Nm].
|
||||
|
||||
This command updates the watchdog timer for the motor.
|
||||
|
||||
#### Request feedback
|
||||
```
|
||||
f motor
|
||||
|
||||
response:
|
||||
pos vel
|
||||
```
|
||||
* `f` for feedback
|
||||
* `pos` is the encoder position in [turns] (float)
|
||||
* `vel` is the encoder velocity in [turns/s] (float)
|
||||
|
||||
#### Update motor watchdog
|
||||
```
|
||||
u motor
|
||||
```
|
||||
* `u` for /u/pdate.
|
||||
* `motor` is the motor number, `0` or `1`.
|
||||
|
||||
This command updates the watchdog timer for the motor, without changing any
|
||||
setpoints.
|
||||
|
||||
#### Parameter reading/writing
|
||||
|
||||
Not all parameters can be accessed via the ASCII protocol but at least all parameters with float and integer type are supported.
|
||||
|
||||
* Reading:
|
||||
```
|
||||
r [property]
|
||||
```
|
||||
* `property` name of the property, as seen in ODrive Tool
|
||||
* response: text representation of the requested value
|
||||
* Example: `r vbus_voltage` => response: `24.087744` <new line>
|
||||
* Writing:
|
||||
```
|
||||
w [property] [value]
|
||||
```
|
||||
* `property` name of the property, as seen in ODrive Tool
|
||||
* `value` text representation of the value to be written
|
||||
* Example: `w axis0.controller.input_pos -123.456`
|
||||
|
||||
#### System commands:
|
||||
* `ss` - Save config
|
||||
* `se` - Erase config
|
||||
* `sr` - Reboot
|
||||
* `sc` - Clear errors
|
||||
@@ -1,138 +0,0 @@
|
||||
# CAN Bus Guide for ODrive
|
||||
|
||||
ODrive v3 supports CAN 2.0b. We've built a [simple protocol](can-protocol.md) (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.
|
||||
|
||||
## What is CAN bus?
|
||||
|
||||
Borrowing from [Wikipeda](https://en.wikipedia.org/wiki/CAN_bus):
|
||||
|
||||
> A Controller Area Network (CAN bus) is a robust vehicle bus standard designed to allow microcontrollers and devices to communicate with each other's applications without a host computer. It is a message-based protocol, designed originally for multiplex electrical wiring within automobiles to save on copper, but it can also be used in many other contexts. For each device, the data in a frame is transmitted sequentially but in such a way that if more than one device transmits at the same time, the highest priority device can continue while the others back off. Frames are received by all devices, including by the transmitting device.
|
||||
|
||||
In simple terms, CAN is a way of communicating between many devices over a single twisted pair of wires. The signal is transmitted as the difference in voltage between the two wires (differential signalling), which makes it very robust against noise. Instead of using a unique address (like I2C) or a select pin (like SPI), CAN *messages* have a unique ID that also acts as the priority. At the beginning of a message frame, all devices talk and read at the same time. As the message ID is transmitted, the lowest value "wins" and that message will be transmitted (ID **0** has the *highest* priority). All other devices will wait for the next chance to send. If two devices send the same message ID at the same time, they will conflict and a bus failure may occur. Make sure your devices can never send the same message ID at the same time!
|
||||
|
||||
See also this great article from Danfoss that quickly describes how to put together the wiring for a CAN bus https://danfosseditron.zendesk.com/hc/en-gb/articles/360042232992-CAN-bus-physical-layer
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Why use CAN?
|
||||
|
||||
CAN is convenient for its simple and robust Physical Layer (PHY) that requires only a twisted pair of wires and a 120ohm termination resistor at each end. It has low jitter and low latency, because there is no host computer. It is relatively fast (CAN 2.0b supports 1 Mbps). Messages are easy to configure and load with data. Transceivers and controllers are inexpensive and widely available, thanks to its use in automotive.
|
||||
|
||||
## Hardware Setup
|
||||
ODrive assumes the CAN PHY is a standard differential twisted pair in a linear bus configuration with 120 ohm termination resistance at each end. ODrive versions less than V3.5 include a soldered 120 ohm termination resistor, but ODrive versions V3.5 and greater implement a dip switch to toggle the termination. ODrive uses 3.3v as the high output, but conforms to the CAN PHY requirement of achieving a differential voltage > 1.5V to represent a "0". As such, it is compatible with standard 5V bus architectures.
|
||||
|
||||
## Setting up CAN on ODrive
|
||||
|
||||
CANSimple breaks the CAN Message ID into two parts: An axis ID and a command ID. By default, CAN is enabled on the ODrive, where Axis 0 has ID 0, and Axis 1 has ID 1. The ID of each axis should be unique; each should be set via `odrivetool` before connecting to the bus with the command:
|
||||
|
||||
`<odrv>.<axis>.config.can.node_id = <number>`
|
||||
|
||||
By default, ODrive supports a value up to 63 (`0x3F`). See [can-protocol.md](can-protocol.md) for more information.
|
||||
|
||||
You should also set the CAN bus speed on ODrive with the command `<odrv>.can.config.baud_rate = <number>`
|
||||
|
||||
| Speed | Value |
|
||||
| --------- | ------- |
|
||||
| 125 kbps | 125000 |
|
||||
| 250 kbps | 250000 |
|
||||
| 500 kbps | 500000 |
|
||||
| 1000 kbps | 1000000 |
|
||||
|
||||
That's it! You're ready to set up your host device.
|
||||
|
||||
### Example
|
||||
```Python
|
||||
odrv0.axis0.config.can.node_id = 0
|
||||
odrv0.axis1.config.can.node_id = 1
|
||||
odrv0.can.config.baud_rate = 250000
|
||||
```
|
||||
|
||||
## Setting up a Raspberry Pi for CAN communications
|
||||
First, you will need a CAN Hat for your Raspberry Pi. We are using [this CAN hat](https://www.amazon.com/Raspberry-Long-Distance-Communication-Transceiver-SN65HVD230/dp/B07DQPYFYV).
|
||||
|
||||
Setting up the Raspberry Pi essentially involves the following:
|
||||
1. Enable SPI communications to the MCP2515
|
||||
2. Install `can-utils` with `apt-get install can-utils`
|
||||
3. Creating a connection between your application and the `can0` socket
|
||||
|
||||
There are many tutorials for this process. [This one is pretty good](https://www.hackster.io/youness/how-to-connect-raspberry-pi-to-can-bus-b60235), and [this recent forum post](https://www.raspberrypi.org/forums/viewtopic.php?t=296117) also works. However, be careful. You have to set the correct parameters for the particular CAN hat you're using!
|
||||
|
||||
1. Set the correct oscillator value
|
||||
|
||||
We configure the MCP2515 in section 2.2 of the tutorial, but the hat we recommend uses a 12MHz crystal instead of a 16 MHz crystal. If you're not sure what value to use, the top of the [oscillator](https://en.wikipedia.org/wiki/Crystal_oscillator) will have the value printed on it in MHz.
|
||||
|
||||
My Settings:
|
||||
```
|
||||
dtparam=spi-on
|
||||
dtoverlay=mcp2515-can0,oscillator=12000000,interrupt=25
|
||||
dtoverlay=spi0-hw-cs
|
||||
```
|
||||
|
||||
2. Use the correct CAN baud rate
|
||||
|
||||
By default, ODrive uses 250 kbps (250000) but the tutorial is using 500 kbps. Make sure you use the value set earlier on the ODrive.
|
||||
|
||||
```
|
||||
sudo ip link set can0 up type can bitrate 250000
|
||||
```
|
||||
|
||||
### Wiring ODrive to CAN
|
||||
The CANH and CANL pins on J2 are used for CAN communication. Connect CANH to CANH on all other devices, and CANL to CANL.
|
||||
|
||||
If your ODrive is the "last" (furthest) device on the bus, you can use the on-board 120 Ohm termination resistor by switching the DIP switch to "CAN 120R". Otherwise, add an external resistor.
|
||||
|
||||
|
||||
|
||||
### Verifying Communcation
|
||||
|
||||
By default, each ODrive axis will send a heartbeat message at 10Hz. We can confirm our ODrive communication is working by starting the `can0` interface, and then reading from it:
|
||||
|
||||
```
|
||||
sudo ip link set can0 up type can bitrate 250000
|
||||
candump can0 -xct z -n 10
|
||||
```
|
||||
|
||||
This will read the first 10 messages from the ODrive and stop. If you'd like to see all messages, remove the `-n 10` part (hit CTRL+C to exit). The other flags (x, c, t) are adding extra information, colouring, and a timestamp, respectively.
|
||||
|
||||
```
|
||||
$ candump can0 -xct z -n 10
|
||||
(000.000000) can0 RX - - 001 [8] 00 00 00 00 01 00 00 00
|
||||
(000.001995) can0 RX - - 021 [8] 00 00 00 00 08 00 00 00
|
||||
(000.099978) can0 RX - - 001 [8] 00 00 00 00 01 00 00 00
|
||||
(000.101963) can0 RX - - 021 [8] 00 00 00 00 08 00 00 00
|
||||
(000.199988) can0 RX - - 001 [8] 00 00 00 00 01 00 00 00
|
||||
(000.201980) can0 RX - - 021 [8] 00 00 00 00 08 00 00 00
|
||||
(000.299986) can0 RX - - 001 [8] 00 00 00 00 01 00 00 00
|
||||
(000.301976) can0 RX - - 021 [8] 00 00 00 00 08 00 00 00
|
||||
(000.399986) can0 RX - - 001 [8] 00 00 00 00 01 00 00 00
|
||||
(000.401972) can0 RX - - 021 [8] 00 00 00 00 08 00 00 00
|
||||
```
|
||||
|
||||
Alternatively, if you have python can installed (`pip3 install python-can`), you can use the can.viewer script:
|
||||
|
||||
`python3 -m can.viewer -c "can0" -i "socketcan"` which will give you a nice readout. See [the python-can docs](https://python-can.readthedocs.io/en/master/scripts.html#can-viewer) for an example.
|
||||
|
||||
## Commanding the ODrive
|
||||
|
||||
Now that we've verified the communication is working, we can try commanding the ODrive. Make sure your ODrive is configured and working properly over USB with `odrivetool` before continuing. See the [Getting Started Guide](getting-started.md) for help with first-time configuration.
|
||||
|
||||
To move the ODrive, we use the command `Set Input Pos`, or cmd ID `0x00C`. First we create a message with this ID, and then "OR" in the axis ID. Then we create an 8-byte array of data with input position that we want, with a float value turned into bytes... this can be a pain though.
|
||||
|
||||
## DBC Files
|
||||
|
||||
A DBC file (.dbc) is a database of all the messages and signals in a CAN protocol. 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!
|
||||
|
||||
* [CANSimple DBC File](../tools/odrive-cansimple.dbc)
|
||||
* [CANSimple DBC Generator Script](../tools/create_can_dbc.py)
|
||||
|
||||
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.
|
||||
|
||||
1. Load the database into memory
|
||||
2. Use `encode_message()` to get a byte array representation of data for sending
|
||||
3. Use `decode_message()` to get a dictionary representation of data for receiving
|
||||
|
||||
The [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.
|
||||
|
||||
If you're using C++, then you can use the [CANHelpers](../Firmware/communication/can/can_helpers.hpp) single-header library to do this instead, although the DBC file isn't used.
|
||||
@@ -1,111 +0,0 @@
|
||||
# CAN Protocol
|
||||
|
||||
This document describes the CAN Protocol. For examples of usage, check out our [CAN Guide!](can-guide.md)
|
||||
|
||||
|
||||
---
|
||||
## Configuring ODrive for CAN
|
||||
Configuration of the CAN parameters should be done via USB before putting the device on the bus.
|
||||
|
||||
To set the desired baud rate, use `<odrv>.can.config.baud_rate = <value>`.
|
||||
|
||||
Each axis looks like a separate node on the bus. Thus, they both have the two properties `can_node_id` and `can_node_id_extended`. The node ID can be from 0 to 63 (0x3F) inclusive, or, if extended CAN IDs are used, from 0 to 16777215 (0xFFFFFF). If you want to connect more than one ODrive on a CAN bus, you must set different node IDs for the second ODrive or they will conflict and crash the bus.
|
||||
|
||||
### Example Configuration
|
||||
|
||||
```
|
||||
odrv0.axis0.config.can_node_id = 3
|
||||
odrv0.axis1.config.can_node_id = 1
|
||||
odrv0.can.config.baud_rate = 500000
|
||||
odrv0.save_configuration()
|
||||
odrv0.reboot()
|
||||
```
|
||||
|
||||
---
|
||||
## Transport Protocol
|
||||
We've implemented a very basic CAN protocol that we call "CAN Simple" to get users going with ODrive. This protocol is sufficiently abstracted that it is straightforward to add other protocols such as CANOpen, J1939, or Fibre over ISO-TP in the future. Unfortunately, implementing those protocols is a lot of work, and we wanted to give users a way to control ODrive's basic functions via CAN sooner rather than later.
|
||||
|
||||
### CAN Frame
|
||||
At its most basic, the CAN Simple frame looks like this:
|
||||
|
||||
* Upper 6 bits - Node ID - max 0x3F (or 0xFFFFFF when using extended CAN IDs)
|
||||
* Lower 5 bits - Command ID - max 0x1F
|
||||
|
||||
To understand how the Node ID and Command ID interact, let's look at an example
|
||||
|
||||
The 11-bit Arbitration ID is setup as follows:
|
||||
|
||||
`can_id = axis_id << 5 | cmd_id`
|
||||
|
||||
For example, an Axis ID of `0x01` with a command of `0x0C` would be result in `0x2C`:
|
||||
|
||||
`0x01 << 5 | 0x0C = 0x2C`
|
||||
|
||||
### Messages
|
||||
|
||||
CMD ID | Name | Sender | Signals | Start byte | Signal Type | Bits | Factor | Offset
|
||||
--: | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :--
|
||||
0x000 | CANOpen NMT Message\*\* | Master | - | - | - | - | - | -
|
||||
0x001 | ODrive Heartbeat Message | Axis | Axis Error<br>Axis Current State<br>Controller Status | 0<br>4<br>7 | Unsigned Int<br>Unsigned Int<br>Bitfield | 32<br>8<br>8 | -<br>-<br>- | -<br>-<br>-
|
||||
0x002 | ODrive Estop Message | Master | - | - | - | - | - | -
|
||||
0x003 | Get Motor Error\* | Axis | Motor Error | 0 | Unsigned Int | 64 | 1 | 0
|
||||
0x004 | Get Encoder Error\* | Axis | Encoder Error | 0 | Unsigned Int | 32 | 1 | 0
|
||||
0x005 | Get Sensorless Error\* | Axis | Sensorless Error | 0 | Unsigned Int | 32 | 1 | 0
|
||||
0x006 | Set Axis Node ID | Master | Axis CAN Node ID | 0 | Unsigned Int | 32 | 1 | 0
|
||||
0x007 | Set Axis Requested State | Master | Axis Requested State | 0 | Unsigned Int | 32 | 1 | 0
|
||||
0x008 | Set Axis Startup Config | Master | - Not yet implemented - | - | - | - | - | -
|
||||
0x009 | Get Encoder Estimates\* | Master | Encoder Pos Estimate<br>Encoder Vel Estimate | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x00A | Get Encoder Count\* | Master | Encoder Shadow Count<br>Encoder Count in CPR | 0<br>4 | Signed Int<br>Signed Int | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x00B | Set Controller Modes | Master | Control Mode<br>Input Mode | 0<br>4 | Signed Int<br>Signed Int | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x00C | Set Input Pos | Master | Input Pos<br>Vel FF<br>Torque FF | 0<br>4<br>6 | IEEE 754 Float<br>Signed Int<br>Signed Int | 32<br>16<br>16 | 1<br>0.001<br>0.001 | 0<br>0<br>0
|
||||
0x00D | Set Input Vel | Master | Input Vel<br>Torque FF | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x00E | Set Input Torque | Master | Input Torque | 0 | IEEE 754 Float | 32 | 1 | 0
|
||||
0x00F | Set Limits | Master | Velocity Limit<br>Current Limit | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br> | 1<br>1 | 0<br>0
|
||||
0x010 | Start Anticogging | Master | - | - | - | - | - | -
|
||||
0x011 | Set Traj Vel Limit | Master | Traj Vel Limit | 0 | IEEE 754 Float | 32 | 1 | 0
|
||||
0x012 | Set Traj Accel Limits | Master | Traj Accel Limit<br>Traj Decel Limit | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x013 | Set Traj Inertia | Master | Traj Inertia | 0 | IEEE 754 Float | 32 | 1 | 0
|
||||
0x014 | Get IQ\* | Axis | Iq Setpoint<br>Iq Measured | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x015 | Get Sensorless Estimates\* | Master | Sensorless Pos Estimate<br>Sensorless Vel Estimate | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x016 | Reboot ODrive | Master\*\*\* | - | - | - | - | - | -
|
||||
0x017 | Get Vbus Voltage | Master\*\*\* | Vbus Voltage | 0 | IEEE 754 Float | 32 | 1 | 0
|
||||
0x018 | Clear Errors | Master | - | - | - | - | - | -
|
||||
0x019 | Set Linear Count | Master | Position | 0 | Signed Int | 32 | 1 | 0
|
||||
0x01A | Set Position Gain | Master | Pos Gain | 0 | IEEE 754 Float | 32 | 1 | 0
|
||||
0x01B | Set Vel Gains | Master | Vel Gain<br>Vel Integrator Gain | 0<br>4 | IEEE 754 Float<br>IEEE 754 Float | 32<br>32 | 1<br>1 | 0<br>0
|
||||
0x700 | CANOpen Heartbeat Message\*\* | Slave | - | - | - | - | - | -
|
||||
-|-|-|----------------------------------|-|--------------------|-|-|-
|
||||
|
||||
All multibyte values are little endian (aka Intel format, aka least significant byte first).
|
||||
|
||||
\* Note: These messages are call & response. The Master node sends a message with the RTR bit set, and the axis responds with the same ID and specified payload.
|
||||
\*\* Note: These CANOpen messages are reserved to avoid bus collisions with CANOpen devices. They are not used by CAN Simple.
|
||||
\*\*\* Note: These messages can be sent to either address on a given ODrive board.
|
||||
|
||||
---
|
||||
|
||||
### Cyclic Messages
|
||||
Cyclic messages are sent by ODrive on a timer without a request. As of `fw0.5.4`, the Cyclic messsages are:
|
||||
|
||||
ID | Name | Rate (ms)
|
||||
--: | :-- | :--
|
||||
0x001 | ODrive Heartbeat Message | 100
|
||||
0x009 | Encoder Estimates | 10
|
||||
|
||||
These can be configured for each axis, see e.g. `axis.config.can`.
|
||||
|
||||
---
|
||||
|
||||
### Interoperability with CANopen
|
||||
You can deconflict with CANopen like this:
|
||||
|
||||
`odrv0.axis0.config.can.node_id = 0x010` - Reserves messages 0x200 through 0x21F
|
||||
`odrv0.axis1.config.can.node_id = 0x018` - Reserves messages 0x300 through 0x31F
|
||||
|
||||
It may not be obvious, but this allows for some compatibility with CANOpen. Although the address space 0x200 and 0x300 correspond to receive PDO base addresses, we can guarantee they will not conflict if all CANopen node IDs are >= 32. E.g.:
|
||||
|
||||
CANopen nodeID = 35 = 0x23
|
||||
Receive PDO 0x200 + nodeID = 0x223, which does not conflict with the range [0x200 : 0x21F]
|
||||
|
||||
Be careful that you don't assign too many nodeIDs per PDO group. Four CAN Simple nodes (32*4) is all of the available address space of a single PDO. If the bus is strictly ODrive CAN Simple nodes, a simple sequential Node ID assignment will work fine.
|
||||
|
||||
105
docs/commands.md
105
docs/commands.md
@@ -1,105 +0,0 @@
|
||||
# Parameters & Commands
|
||||
|
||||
We will use the `<odrv>` as a placeholder for any ODrive object. Every ODrive controller is an ODrive object. In `odrivetool` this is usually `odrv0`. Furthermore we use `<axis>` as a placeholder for any axis, which is an attribute of an ODrive object (for example `odrv0.axis0`). An axis represents where the motors are connected. (axis0 for M0 or axis1 for M1)
|
||||
|
||||
### Table of contents
|
||||
<!-- TOC depthFrom:2 depthTo:2 -->
|
||||
|
||||
- [Per-Axis commands](#per-axis-commands)
|
||||
- [System monitoring commands](#system-monitoring-commands)
|
||||
- [General system commands](#general-system-commands)
|
||||
- [Setting up sensorless](#setting-up-sensorless)
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
## Per-Axis commands
|
||||
|
||||
For the most part, both axes on the ODrive can be controlled independently.
|
||||
|
||||
### State Machine
|
||||
|
||||
The current state of an axis is indicated by [`<axis>.current_state`](api/odrive.axis#current_state). The user can request a new state by assigning a new value to [`<axis>.requested_state`](api/odrive.axis#current_state). The default state after startup is `AXIS_STATE_IDLE`. A description of all states can be found [here](api/odrive.axis.axisstate).
|
||||
|
||||
|
||||
### Startup Procedure
|
||||
|
||||
By default the ODrive takes no action at startup and goes to idle immediately.
|
||||
In order to change what startup procedures are used, set the startup procedures you want to `True`.
|
||||
The ODrive will sequence all enabled startup actions selected in the order shown below.
|
||||
|
||||
* `<axis>.config.startup_motor_calibration`
|
||||
* `<axis>.config.startup_encoder_index_search`
|
||||
* `<axis>.config.startup_encoder_offset_calibration`
|
||||
* `<axis>.config.startup_closed_loop_control`
|
||||
|
||||
See [here](api/odrive.axis.axisstate) for a description of each state.
|
||||
|
||||
### Control Mode
|
||||
The default control mode is position control.
|
||||
If you want a different mode, you can change `<axis>.controller.config.control_mode`.
|
||||
Possible values are listed [here](api/odrive.controller.controlmode).
|
||||
|
||||
### Input Mode
|
||||
|
||||
As of version v0.5.0, ODrive now intercepts the incoming commands and can apply filters to them. The old protocol values `pos_setpoint`, `vel_setpoint`, and `current_setpoint` are still used internally by the closed-loop cascade control, but the user cannot write to them directly. This allows us to condense the number of ways the ODrive accepts motion commands. The new commands are:
|
||||
|
||||
### Control Commands
|
||||
* `<axis>.controller.input_pos = <turn>`
|
||||
* `<axis>.controller.input_vel = <turn/s>`
|
||||
* `<axis>.controller.input_torque = <torque in Nm>`
|
||||
|
||||
Modes can be selected by changing `<axis>.controller.config.input_mode`.
|
||||
The default input mode is `INPUT_MODE_PASSTHROUGH`.
|
||||
Possible values are listed [here](api/odrive.controller.inputmode).
|
||||
|
||||
## System monitoring commands
|
||||
|
||||
### Encoder position and velocity
|
||||
* View encoder position with `<axis>.encoder.pos_estimate` [turns] or `<axis>.encoder.pos_est_counts` [counts]
|
||||
* View rotational velocity with `<axis>.encoder.vel_estimate` [turn/s] or `<axis>.encoder.vel_est_counts` [count/s]
|
||||
|
||||
### Motor current and torque estimation
|
||||
* View the commanded motor current with `<axis>.motor.current_control.Iq_setpoint` [A]
|
||||
* View the measured motor current with `<axis>.motor.current_control.Iq_measured` [A]. If you find that this returns noisy data then use the command motor current instead. The two values should be close so long as you are not approaching the maximum achievable rotational velocity of your motor for a given supply voltage, in which case the commanded current may become larger than the measured current.
|
||||
|
||||
Using the motor current and the known KV of your motor you can estimate the motors torque using the following relationship: Torque [N.m] = 8.27 * Current [A] / KV.
|
||||
|
||||
## General system commands
|
||||
|
||||
### Saving the configuration
|
||||
|
||||
All variables that are part of a `[...].config` object can be saved to non-volatile memory on the ODrive so they persist after you remove power. The relevant commands are:
|
||||
|
||||
* `<odrv>.save_configuration()`: Stores the configuration to persistent memory on the ODrive.
|
||||
* `<odrv>.erase_configuration()`: Resets the configuration variables to their factory defaults. This also reboots the device.
|
||||
|
||||
### Diagnostics
|
||||
|
||||
* `<odrv>.serial_number`: A number that uniquely identifies your device. When printed in upper case hexadecimal (`hex(<odrv>.serial_number).upper()`), this is identical to the serial number indicated by the USB descriptor.
|
||||
* `<odrv>.fw_version_major`, `<odrv>.fw_version_minor`, `<odrv>.fw_version_revision`: The firmware version that is currently running.
|
||||
* `<odrv>.hw_version_major`, `<odrv>.hw_version_minor`, `<odrv>.hw_version_revision`: The hardware version of your ODrive.
|
||||
|
||||
## Setting up sensorless
|
||||
The ODrive can run without encoder/hall feedback, but there is a minimum speed, usually around a few hundred RPM. In other words, sensorless mode does not support stopping or changing direction!
|
||||
|
||||
Sensorless mode starts by ramping up the motor speed in open loop control and then switches to closed loop control automatically. The sensorless speed ramping parameters are in `axis.config.sensorless_ramp` The `vel` and `accel` (in [radians/s] and [radians/s^2]) control the speed that the ramp tries to reach and how quickly it gets there. When the ramp reaches `sensorless_ramp.vel`, `controller.input_vel` is automatically set to the same velocity, in [turns/s], and the state switches to closed loop control.
|
||||
|
||||
If your motor comes to a stop after the ramp, try incrementally raising the `vel` parameter. The goal is to be above the minimum speed necessary for sensorless position and speed feedback to converge - this is not well-parameterized per motor. The parameters suggested below work for the D5065 motor, with 270KV and 7 pole pairs. If your motor grinds and skips during the ramp, lower the `accel` parameter until it is tolerable.
|
||||
|
||||
Below are some suggested starting parameters that you can use for the ODrive D5065 motor. Note that you _must_ set the `pm_flux_linkage` correctly for sensorless mode to work. Motor calibration and setup must also be completed before sensorless mode will work.
|
||||
|
||||
|
||||
```
|
||||
odrv0.axis0.controller.config.vel_gain = 0.01
|
||||
odrv0.axis0.controller.config.vel_integrator_gain = 0.05
|
||||
odrv0.axis0.controller.config.control_mode = CONTROL_MODE_VELOCITY_CONTROL
|
||||
odrv0.axis0.controller.config.vel_limit = <a value greater than axis.config.sensorless_ramp.vel / (2pi * <pole_pairs>)>
|
||||
odrv0.axis0.motor.config.current_lim = 2 * odrv0.axis0.config.sensorless_ramp.current
|
||||
odrv0.axis0.sensorless_estimator.config.pm_flux_linkage = 5.51328895422 / (<pole pairs> * <motor kv>)
|
||||
odrv0.axis0.config.enable_sensorless_mode = True
|
||||
```
|
||||
|
||||
To start the motor:
|
||||
```
|
||||
<axis>.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL
|
||||
```
|
||||
@@ -15,8 +15,8 @@ import sys
|
||||
|
||||
sys.path.insert(0, os.path.abspath('.'))
|
||||
sys.path.insert(0, os.path.abspath('./figures'))
|
||||
sys.path.insert(0, os.path.abspath('../exts')) # needed for fibre_autodoc extension
|
||||
sys.path.insert(0, os.path.abspath('../../tools/fibre-tools')) # needed for fibre_autodoc extension
|
||||
sys.path.insert(0, os.path.abspath('./exts')) # needed for fibre_autodoc extension
|
||||
sys.path.insert(0, os.path.abspath('../tools/fibre-tools')) # needed for fibre_autodoc extension
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
@@ -66,7 +66,7 @@ html_theme = "sphinx_rtd_theme"
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
fibre_interface_files = ['../../Firmware/odrive-interface.yaml']
|
||||
fibre_interface_files = ['../Firmware/odrive-interface.yaml']
|
||||
|
||||
autosummary_generate = False
|
||||
|
||||
@@ -1,35 +0,0 @@
|
||||
# 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)
|
||||
|
||||
|
||||
|
||||
## 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!
|
||||
* 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:
|
||||
|
||||
|
||||
|
||||
* 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
|
||||
@@ -1,56 +0,0 @@
|
||||
# Configuring Visual Studio Code
|
||||
|
||||
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](developer-guide#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++ `ext install ms-vscode.cpptools`
|
||||
* Cortex-Debug `ext install marus25.cortex-debug`
|
||||
* Cortex-Debug: Device Support Pack - STM32F4 `ext install marus25.cortex-debug-dp-stm32f4`
|
||||
* Recommended Extensions:
|
||||
* Include Autocomplete
|
||||
* Path Autocomplete
|
||||
* Auto Comment Blocks
|
||||
1. Create an environment variable named `ARM_GCC_ROOT` whose value is the location of the `GNU Arm Embedded Toolchain` (.e.g `C:\Program Files (x86)\GNU Tools Arm Embedded\7 2018-q2-update`) that you installed in the prerequisites section of the developer's guide. This is not strictly needed for Linux or Mac, and you can alternatively use the `Cortex-debug: Arm Toolchain Path` setting in VSCode extension settings.
|
||||
1. Relaunch VSCode
|
||||
1. Open the VSCode Workspace file, which is located in the root of the ODrive repository. It is called `ODrive_Workspace.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.
|
||||
|
||||
## Building the Firmware
|
||||
* Terminal -> Run Build Task (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd>)
|
||||
|
||||
A terminal window will open with your native shell. VSCode is configured to run the command `make -j4` in this terminal.
|
||||
|
||||
## Flashing the Firmware
|
||||
* Terminal -> 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 connect to the board using the [odrivetool](getting-started#start-odrivetool).
|
||||
|
||||
## Debugging
|
||||
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
|
||||
* Set `CONFIG_DEBUG=true` in the tup.config file
|
||||
* Flash the board with the newest code (starting debug session doesn't do this)
|
||||
* In the _Run_ tab (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>), select "Debug ODrive (Firmware)"
|
||||
* Press _Start Debugging_ (or press <kbd>F5</kbd>)
|
||||
* 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.
|
||||
* _Continue_ (<kbd>F5</kbd>)
|
||||
* 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 (<kbd>Shift</kbd>+<kbd>F5</kbd>) the debugger. It will kill your openOCD process too.
|
||||
|
||||
## Cleaning the Build
|
||||
This sometimes needs to be done if you change branches.
|
||||
* Open a terminal (View -> Integrated Terminal) and enter `make clean`
|
||||
@@ -1,100 +0,0 @@
|
||||
|
||||
The default control mode is unfiltered position control in the absolute encoder reference frame. You may wish to use a controlled trajectory instead. Or you may wish to control position in a circular frame to allow continuous rotation forever without growing the numeric value of the setpoint too large.
|
||||
|
||||
You may also wish to control velocity (directly or with a ramping filter).
|
||||
You can also directly control the current of the motor, which is proportional to torque.
|
||||
|
||||
- [Filtered position control](#filtered-position-control)
|
||||
- [Trajectory control](#trajectory-control)
|
||||
- [Circular position control](#circular-position-control)
|
||||
- [Velocity control](#velocity-control)
|
||||
- [Ramped velocity control](#ramped-velocity-control)
|
||||
- [Torque control](#torque-control)
|
||||
|
||||
|
||||
### Filtered position control
|
||||
Asking the ODrive controller to go as hard as it can to raw setpoints may result in jerky movement. Even if you are using a planned trajectory generated from an external source, if that is sent at a modest frequency, the ODrive may chase each stair in the incoming staircase in a jerky way. In this case, a good starting point for tuning the filter bandwidth is to set it to one half of your setpoint command rate.
|
||||
|
||||
You can use the second order position filter in these cases.
|
||||
Set the filter bandwidth: `axis.controller.config.input_filter_bandwidth = 2.0` [1/s]<br>
|
||||
Activate the setpoint filter: `axis.controller.config.input_mode = INPUT_MODE_POS_FILTER`.<br>
|
||||
You can now control the velocity with `axis.controller.input_pos = 1` [turns].
|
||||
|
||||
<br>
|
||||
Step response of a 1000 to 0 position input with a filter bandwidth of 1.0 [/sec].
|
||||
|
||||
### Trajectory control
|
||||
See the **Usage** section for usage details.<br>
|
||||
This mode lets you smoothly accelerate, coast, and decelerate the axis from one position to another. With raw position control, the controller simply tries to go to the setpoint as quickly as possible. Using a trajectory lets you tune the feedback gains more aggressively to reject disturbance, while keeping smooth motion.
|
||||
|
||||
<br>
|
||||
In the above image blue is position and orange is velocity.
|
||||
|
||||
#### Parameters
|
||||
```
|
||||
<odrv>.<axis>.trap_traj.config.vel_limit = <Float>
|
||||
<odrv>.<axis>.trap_traj.config.accel_limit = <Float>
|
||||
<odrv>.<axis>.trap_traj.config.decel_limit = <Float>
|
||||
<odrv>.<axis>.controller.config.inertia = <Float>
|
||||
```
|
||||
|
||||
`vel_limit` is the maximum planned trajectory speed. This sets your coasting speed.<br>
|
||||
`accel_limit` is the maximum acceleration in turns / sec^2<br>
|
||||
`decel_limit` is the maximum deceleration in turns / sec^2<br>
|
||||
`controller.config.inertia` is a value which correlates acceleration (in turns / sec^2) and motor torque. It is 0 by default. It is optional, but can improve response of your system if correctly tuned. Keep in mind this will need to change with the load / mass of your system.
|
||||
|
||||
All values should be strictly positive (>= 0).
|
||||
|
||||
Keep in mind that you must still set your safety limits as before. It is recommended you set these a little higher ( > 10%) than the planner values, to give the controller enough control authority.
|
||||
```
|
||||
<odrv>.<axis>.motor.config.current_lim = <Float>
|
||||
<odrv>.<axis>.controller.config.vel_limit = <Float>
|
||||
```
|
||||
|
||||
#### Usage
|
||||
Make sure you are in position control mode. To activate the trajectory module, set the input mode to trajectory:
|
||||
```
|
||||
axis.controller.config.input_mode = INPUT_MODE_TRAP_TRAJ
|
||||
```
|
||||
|
||||
Simply send a position command to execute the move:
|
||||
```
|
||||
<odrv>.<axis>.controller.input_pos = <Float>
|
||||
```
|
||||
|
||||
Use the `move_incremental` function to move to a relative position.
|
||||
To set the goal relative to the current actual position, use `from_goal_point = False`
|
||||
To set the goal relative to the previous destination, use `from_goal_point = True`
|
||||
```
|
||||
<odrv>.<axis>.controller.move_incremental(pos_increment, from_goal_point)
|
||||
```
|
||||
|
||||
You can also execute a move with the [appropriate ascii command](ascii-protocol.md#motor-trajectory-command).
|
||||
|
||||
### Circular position control
|
||||
|
||||
To enable Circular position control, set `axis.controller.config.circular_setpoints = True`
|
||||
|
||||
This mode is useful for continuous incremental position movement. For example a robot rolling indefinitely, or an extruder motor or conveyor belt moving with controlled increments indefinitely.
|
||||
In the regular position mode, the `input_pos` would grow to a very large value and would lose precision due to floating point rounding.
|
||||
|
||||
In this mode, the controller will try to track the position within only one turn of the motor. Specifically, `input_pos` is expected in the range `[0, 1)`. If the `input_pos` is incremented to outside this range (say via step/dir input), it is automatically wrapped around into the correct value.
|
||||
Note that in this mode `encoder.pos_circular` is used for feedback instead of `encoder.pos_estimate`.
|
||||
|
||||
If you try to increment the axis with a large step in one go that exceeds `1` turn, the motor will go to the same angle around the wrong way. This is also the case if there is a large disturbance. If you have an application where you would like to handle larger steps, you can use a larger circular range. Set `controller.config.circular_setpoints_range = N`. Choose N to give you an appropriate circular space for your application.
|
||||
|
||||
### Velocity control
|
||||
Set `axis.controller.config.control_mode = CONTROL_MODE_VELOCITY_CONTROL`.<br>
|
||||
You can now control the velocity with `axis.controller.input_vel = 1` [turn/s].
|
||||
|
||||
### Ramped velocity control
|
||||
Set `axis.controller.config.control_mode = CONTROL_MODE_VELOCITY_CONTROL`.<br>
|
||||
Set the velocity ramp rate (acceleration): `axis.controller.config.vel_ramp_rate = 0.5` [turn/s^2]<br>
|
||||
Activate the ramped velocity mode: `axis.controller.config.input_mode = INPUT_MODE_VEL_RAMP`.<br>
|
||||
You can now control the velocity with `axis.controller.input_vel = 1` [turn/s].
|
||||
|
||||
### Torque control
|
||||
Set `axis.controller.config.control_mode = CONTROL_MODE_TORQUE_CONTROL`.<br>
|
||||
You can now control the torque with `axis.controller.input_torque = 0.1` [Nm].
|
||||
|
||||
Note: If you exceed `vel_limit` in torque control mode, the current is reduced. To disable this, set `axis.controller.enable_torque_mode_vel_limit = False`.
|
||||
@@ -1,62 +0,0 @@
|
||||
# Control
|
||||
|
||||
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. In torque control mode, only the current controller is used.
|
||||
|
||||
|
||||
|
||||
Each stage of the control loop is a variation on a [PID controller](https://en.wikipedia.org/wiki/PID_controller). A PID controller is a mathematical model that can be adapted to control a wide variety of systems. This flexibility is essential as it allows the ODrive to be used to control all kinds of mechanical systems.
|
||||
|
||||
* Note: The controller has been updated to use `torque` in Newton-meters instead of current at the "system" level. There is a `torque_constant` parameter which converts between torque and current, after which the rest of this explanation still holds.
|
||||
|
||||
### Position loop:
|
||||
The position controller is a P loop with a single proportional gain.
|
||||
```text
|
||||
pos_error = pos_setpoint - pos_feedback
|
||||
vel_cmd = pos_error * pos_gain + vel_feedforward
|
||||
```
|
||||
|
||||
### Velocity loop:
|
||||
The velocity controller is a PI loop.
|
||||
```text
|
||||
vel_error = vel_cmd - vel_feedback
|
||||
current_integral += vel_error * vel_integrator_gain
|
||||
current_cmd = vel_error * vel_gain + current_integral + current_feedforward
|
||||
```
|
||||
|
||||
### Current loop:
|
||||
The current controller is a PI loop.
|
||||
```text
|
||||
current_error = current_cmd - current_fb
|
||||
voltage_integral += current_error * current_integrator_gain
|
||||
voltage_cmd = current_error * current_gain + voltage_integral (+ voltage_feedforward when we have motor model)
|
||||
```
|
||||
|
||||
Note: `current_gain` and `current_integrator_gain` are automatically set according to `motor.config.current_control_bandwidth`
|
||||
|
||||
For more detail refer to [controller.cpp](https://github.com/madcowswe/ODrive/blob/master/Firmware/MotorControl/controller.cpp#L86).
|
||||
|
||||
### Controller Details:
|
||||
The ultimate output of the controller is the voltage applied to the gate of each FET to deliver current through each coil of the motor. The current through the motor linearly relates to the torque output of the motor. This means that the inputs to the cascaded controller are theoretically the position (angle), velocity (angle/time), and acceleration (angle/time/time) of the motor. Note that when thinking about the controller from the perpective of the physics of the motor you would expect to see the time in the Velocity and Current loops, but it is absent because the time difference between iterations is always 125 microseconds (8kHz). Because the time difference between controller loops is a constant and can simply be wrapped into the controller gains.
|
||||
|
||||
The output of each stage of the controller is clamped before being fed into the next stage. So after the `vel_cmd` is calculated from the position controller, the `vel_cmd` is clamped to the velocity limit. The `torque_cmd` output of the velocity controller is then clamped and fed to the current controller. Oddly enough the controller class does not contain the current controller, but instead the current controller is housed in the motor class due to the complexity of the motor driver schema.
|
||||
|
||||
The feedforward terms available when using the position or velocity control mode are meant to enable better performance when the dynamics of a system are known and the host controller can predict the motion based on the load. A perfect example of this is the use of the trajectory controller that sets the position, velocity, and torque based on the desired position, velocity, and acceleration. If you take a trapezoidal velocity profile for example, you can imagine on the ramp upward the velocity will be increasing over time, while the torque is a non-zero constant. At the flat portion of the profile the velocity will be a non-zero constant, but the acceleration will be zero. This trajectory controller use case uses the cascaded controller with multiple inputs to achieve the desired motion with the best performance.
|
||||
|
||||
## Tuning
|
||||
Tuning the motor controller is an essential step to unlock the full potential of the ODrive. Tuning allows for the controller to quickly respond to disturbances or changes in the system (such as an external force being applied or a change in the setpoint) without becoming unstable. Correctly setting the three tuning parameters (called gains) ensures that ODrive can control your motors in the most effective way possible. The three values are:
|
||||
* `<axis>.controller.config.pos_gain = 20.0` [(turn/s) / turn]
|
||||
* `<axis>.controller.config.vel_gain = 0.16 ` [Nm/(turn/s)]
|
||||
* `<axis>.controller.config.vel_integrator_gain = 0.32` [Nm/((turn/s) * s)]
|
||||
|
||||
An upcoming feature will enable automatic tuning. Until then, here is a rough tuning procedure:
|
||||
* Set vel_integrator_gain gain to 0
|
||||
* Make sure you have a stable system. If it is not, decrease all gains until you have one.
|
||||
* Increase `vel_gain` by around 30% per iteration until the motor exhibits some vibration.
|
||||
* Back down `vel_gain` to 50% of the vibrating value.
|
||||
* Increase `pos_gain` by around 30% per iteration until you see some overshoot.
|
||||
* Back down `pos_gain` until you do not have overshoot anymore.
|
||||
* The integrator can be set to `0.5 * bandwidth * vel_gain`, where `bandwidth` is the overall resulting tracking bandwidth of your system. Say your tuning made it track commands with a settling time of 100ms (the time from when the setpoint changes to when the system arrives at the new setpoint); this means the bandwidth was 1/(100ms) = 1/(0.1s) = 10hz. In this case you should set the `vel_integrator_gain = 0.5 * 10 * vel_gain`.
|
||||
|
||||
The liveplotter tool can be immensely helpful in dialing in these values. To display a graph that plots the position setpoint vs the measured position value run the following in the ODrive tool:
|
||||
|
||||
`start_liveplotter(lambda:[odrv0.axis0.encoder.pos_estimate, odrv0.axis0.controller.pos_setpoint])`
|
||||
@@ -1,335 +0,0 @@
|
||||
# ODrive Firmware Developer Guide
|
||||
|
||||
This guide is intended for developers who wish to modify the firmware of the ODrive.
|
||||
As such it assumes that you know things like how to use Git, what a compiler is, etc. If that sounds scary, turn around now.
|
||||
|
||||
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 [Changelog](../CHANGELOG.md) to keep track of updates.
|
||||
|
||||
### Table of contents
|
||||
|
||||
<!-- MarkdownTOC depth=2 autolink=true bracket=round -->
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Configuring the build](#configuring-the-build)
|
||||
- [Building and flashing the Firmware](#building-and-flashing-the-firmware)
|
||||
- [Debugging](#debugging)
|
||||
- [Testing](#testing)
|
||||
- [Setting up an IDE](#setting-up-an-ide)
|
||||
- [STM32CubeMX](#stm32cubemx)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Documentation](#documentation)
|
||||
- [Releases](#releases)
|
||||
- [Notes for Contributors](#notes-for-contributors)
|
||||
|
||||
<!-- /MarkdownTOC -->
|
||||
|
||||
<br><br>
|
||||
## Prerequisites
|
||||
|
||||
The recommended tools for ODrive development are:
|
||||
|
||||
* **make**: Used to invoke tup
|
||||
* **Tup**: The build system used to invoke the compile commands
|
||||
* **ARM GNU Compiler**: For cross-compiling code
|
||||
* **ARM GDB**: For debugging the code and stepping through on the device
|
||||
* **OpenOCD**: For flashing the ODrive with the STLink/v2 programmer
|
||||
* **Python 3**, along with the packages `PyYAML`, `Jinja2` and `jsonschema`: For running the Python tools (`odrivetool`). Also required for compiling firmware.
|
||||
|
||||
See below for specific installation instructions for your OS.
|
||||
|
||||
Depending on what you're gonna do, you may not need all of the components.
|
||||
|
||||
Once you have everything, you can verify the correct installation by running:
|
||||
```bash
|
||||
$ arm-none-eabi-gcc --version
|
||||
$ arm-none-eabi-gdb --version
|
||||
$ openocd --version # should be 0.10.0 or later
|
||||
$ tup --version # should be 0.7.5 or later
|
||||
$ python --version # should be 3.7 or later
|
||||
```
|
||||
|
||||
#### Linux (Ubuntu < 20.04)
|
||||
```bash
|
||||
sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
|
||||
sudo apt-get update
|
||||
sudo apt-get install gcc-arm-embedded
|
||||
sudo apt-get install openocd
|
||||
sudo apt-get install git-lfs
|
||||
sudo add-apt-repository ppa:jonathonf/tup && sudo apt-get update && sudo apt-get install tup
|
||||
sudo apt-get install python3 python3-yaml python3-jinja2 python3-jsonschema
|
||||
```
|
||||
|
||||
#### Linux (Ubuntu >= 20.04)
|
||||
```bash
|
||||
sudo apt install gcc-arm-none-eabi
|
||||
sudo apt install openocd
|
||||
sudo apt install git-lfs
|
||||
sudo apt install tup
|
||||
sudo apt install python3 python3-yaml python3-jinja2 python3-jsonschema
|
||||
```
|
||||
|
||||
#### Arch Linux
|
||||
```bash
|
||||
sudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils
|
||||
sudo pacman -S arm-none-eabi-gdb
|
||||
sudo pacman -S git-lfs
|
||||
sudo pacman -S tup
|
||||
sudo pacman -S python python-yaml python-jinja python-jsonschema
|
||||
```
|
||||
* [OpenOCD AUR package](https://aur.archlinux.org/packages/openocd/)
|
||||
|
||||
#### Mac
|
||||
First install [Homebrew](https://brew.sh/). Then you can run these commands in Terminal:
|
||||
```bash
|
||||
brew install armmbed/formulae/arm-none-eabi-gcc
|
||||
brew install --cask osxfuse && brew install tup
|
||||
brew install openocd
|
||||
brew install git-lfs
|
||||
pip3 install PyYAML Jinja2 jsonschema
|
||||
```
|
||||
|
||||
#### Windows
|
||||
__Note__: make sure these programs are not only installed but also added to your `PATH`.
|
||||
|
||||
Some instructions in this document may assume that you're using a bash command prompt, such as the Windows 10 built-in bash or [Git](https://git-scm.com/download/win) bash.
|
||||
|
||||
* [ARM compiler](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
|
||||
* __Note 1__: After installing, create an environment variable named `ARM_GCC_ROOT` whose value is the path you installed to. e.g. `C:\Program Files (x86)\GNU Tools Arm Embedded\7 2018-q2-update`. This variable is used to locate include files for the c/c++ Visual Studio Code extension.
|
||||
* __Note 2__: 8-2018-q4-major seems to have a bug on Windows. Please use 7-2018-q2-update.
|
||||
* [Tup](http://gittup.org/tup/index.html)
|
||||
* [GNU MCU Eclipse's Windows Build Tools](https://github.com/gnu-mcu-eclipse/windows-build-tools/releases)
|
||||
* [Python 3](https://www.python.org/downloads/)
|
||||
* Install Python packages: `pip install PyYAML Jinja2 jsonschema`
|
||||
* [OpenOCD](https://github.com/xpack-dev-tools/openocd-xpack/releases/).
|
||||
* [ST-Link/V2 Drivers](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-utilities/stsw-link009.html)
|
||||
|
||||
<br>
|
||||
|
||||
## Configuring the build
|
||||
|
||||
To customize the compile time parameters, copy or rename the file `Firmware/tup.config.default` to `Firmware/tup.config` and edit the parameters in that file:
|
||||
|
||||
__CONFIG_BOARD_VERSION__: The board version you're using. Can be `v3.1`, `v3.2`, `v3.3`, `v3.4-24V`, `v3.4-48V`, `v3.5-24V`, `v3.5-48V`, etc. Check for a label on the upper side of the ODrive to find out which version you have. Some ODrive versions don't specify the voltage: in that case you can read the value of the main capacitors: 120uF are 48V ODrives, 470uF are 24V ODrives.
|
||||
|
||||
__CONFIG_DEBUG__: Defines whether debugging will be enabled when compiling the firmware; specifically the `-g -gdwarf-2` flags. Note that printf debugging will only function if your tup.config specifies the `USB_PROTOCOL` or `UART_PROTOCOL` as stdout and `DEBUG_PRINT` is defined. See the IDE specific documentation for more information.
|
||||
|
||||
You can also modify the compile-time defaults for all `.config` parameters. You will find them if you search for `AxisConfig`, `MotorConfig`, etc.
|
||||
|
||||
<br><br>
|
||||
## Building and flashing the Firmware
|
||||
|
||||
1. Run `make` in the `Firmware` directory.
|
||||
2. Connect the ODrive via USB and power it up.
|
||||
3. Flash the firmware using [odrivetool dfu](odrivetool#device-firmware-update).
|
||||
|
||||
### Flashing using an STLink/v2 programmer
|
||||
|
||||
* Connect `GND`, `SWD`, and `SWC` on connector J2 to the programmer. Note: Always plug in `GND` first!
|
||||
* 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 `Firmware` directory.
|
||||
__Note__: If you receive the error `can't find target interface/stlink-v2.cfg` or similar, create and set an environment variable named `OPENOCD_SCRIPTS` to the location of the openocd scripts directory.
|
||||
|
||||
If the flashing worked, you can connect to the board using the [odrivetool](getting-started#start-odrivetool).
|
||||
|
||||
<br><br>
|
||||
## Testing
|
||||
_Main article: [Testing](testing.md)_
|
||||
|
||||
<br><br>
|
||||
## Debugging
|
||||
If you're using VSCode, make sure you have the Cortex Debug extension, OpenOCD, and the STLink. You can verify that OpenOCD and STLink are working by ensuring you can flash code. Open the ODrive_Workspace.code-workspace file, and start a debugging session (F5). VSCode will pick up the correct settings from the workspace and automatically connect. Breakpoints can be added graphically in VSCode.
|
||||
|
||||
* 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.
|
||||
|
||||
<br><br>
|
||||
## Setting up an IDE
|
||||
For working with the ODrive code you don't need 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)
|
||||
|
||||
<br><br>
|
||||
## STM32CubeMX
|
||||
This project uses the STM32CubeMX tool to generate startup code and to ease the configuration of the peripherals. You can download it from [here](http://www2.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-configurators-and-code-generators/stm32cubemx.html?icmp=stm32cubemx_pron_pr-stm32cubef2_apr2014&sc=stm32cube-pr2). All CubeMX related files are in `Firmware/Board/v3`.
|
||||
|
||||
You will likely want the pinout for this process. It is available [here](https://docs.google.com/spreadsheets/d/1QXDCs1IRtUyG__M_9WruWOheywb-GhOwFtfPcHuN2Fg/edit#gid=404444347).
|
||||
|
||||
### Maintaining modified generated code
|
||||
When generating the code, STM32CubeMX will nuke everything except some special sections that they provide. These sections are marked like `USER CODE BEGIN`...`USER CODE END`.
|
||||
We used to try to make sure all edits we made to the generated code would only go in these sections, so some code structrure may reflect that.
|
||||
However over time we realized this will not be tenable, so instead we use git to rebase all changes of the generated code whenever we need to regenerate it.
|
||||
We use two special branches that will help us to do this, they are `STM32CubeMX-start` and `STM32CubeMX-end`.
|
||||
How to use these is shown in the following example.
|
||||
|
||||
**Note**: Due to how this rebasing is done, all development that changes the generated code should be done directly on `STM32CubeMX-end`, and not based on `devel`, then follow step 4 below to carry them over to your feature branch. If you did some changes to the generated code based from `devel`, you need to cherry pick just those changes over to `STM32CubeMX-end`.
|
||||
|
||||
### 1. Ensuring a clean slate
|
||||
* We do all changes to the STM32CubeMX config and regenerate the code on top of `STM32CubeMX-start`.
|
||||
* `git checkout STM32CubeMX-start`
|
||||
* Run stm32cubeMX and load the `Firmware/Board/v3/Odrive.ioc` project file.
|
||||
* If the tool asks if you wish to migrate to a new version, choose to download the old firmware package (unless you want to use the latest libraries)
|
||||
* Without changing any settings, press `Project -> Generate code`.
|
||||
* You may need to let it download some drivers and such.
|
||||
* STM32CubeMX may now have a newer version of some of the libraries, so there may be changes to the generated code even though we didn't change any settings. We need to check that everything is still working, and hence check in the changes:
|
||||
* `git config --local core.autocrlf input` - This will tell git that all files should be checked in with LF endings (CubeMX generates CRLF endings).
|
||||
* `git diff` - Ignore the pile of line ending warnings.
|
||||
* If you feel qualified: you can now ispect if CubeMX introduced something stupid. If there were any changes, and they look acceptable, we should commit them:
|
||||
* `git commit -am "Run STM32CubeMX v1.21"` - Replace with actual version of CubeMX
|
||||
|
||||
### 2. Making changes to the STM32CubeMX config
|
||||
* After completing the above steps, make sure the working directory is clean:
|
||||
* `git status` should include "nothing to commit, working tree clean"
|
||||
* Make your changes in STM32CubeMX, save the project and generate the code. (`Project -> Generate code`)
|
||||
* `git diff` - Check that the introduced changes are as expected
|
||||
* If everything looks ok, you can commit your changes.
|
||||
|
||||
### 3. Rebasing the modifications to the generated code
|
||||
* `git checkout STM32CubeMX-end`
|
||||
* `git rebase STM32CubeMX-start`
|
||||
* Make sure the rebase finishes, fixing any conflicts that may arise
|
||||
|
||||
### 4. Merge new STM32CubeMX code to your feature branch
|
||||
Simply merge the new state at `STM32CubeMX-end` into your feature branch.
|
||||
* `git checkout your-feature`
|
||||
* `git merge STM32CubeMX-end`
|
||||
|
||||
### 5. Pushing back upstream
|
||||
* Generate a PR like normal for your feature.
|
||||
* Make sure youhave pushed to the `STM32CubeMX-start` and `STM32CubeMX-end` branches on your fork.
|
||||
* Make a note in your PR to the maintainer that they need to update the STM32CubeMX branches when they merge the PR.
|
||||
|
||||
<br><br>
|
||||
## Troubleshooting
|
||||
|
||||
### `LIBUSB_ERROR_IO` when flashing with the STLink/v2
|
||||
|
||||
**Problem:** when I try to flash the ODrive with the STLink using `make flash` I get this error:
|
||||
```
|
||||
Open On-Chip Debugger 0.10.0
|
||||
Licensed under GNU GPL v2
|
||||
For bug reports, read
|
||||
http://openocd.org/doc/doxygen/bugs.html
|
||||
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
|
||||
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
|
||||
adapter speed: 2000 kHz
|
||||
adapter_nsrst_delay: 100
|
||||
none separate
|
||||
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
|
||||
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
|
||||
Info : clock speed 1800 kHz
|
||||
Error: libusb_open() failed with LIBUSB_ERROR_IO
|
||||
Error: open failed
|
||||
in procedure 'init'
|
||||
in procedure 'ocd_bouncer'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
This happens from time to time.
|
||||
1. Unplug the STLink and all ODrives from your computer
|
||||
2. Power off the ODrive you're trying to flash
|
||||
3. Plug in the STLink into your computer
|
||||
4. Power on the ODrive
|
||||
5. Run `make flash` again
|
||||
|
||||
### `Warn : Cannot identify target as a STM32 family.` when flashing using openocd
|
||||
|
||||
**Problem:** When I try to flash ODrive v4.1 with `make flash` then I get:
|
||||
```
|
||||
[...]
|
||||
** Programming Started **
|
||||
auto erase enabled
|
||||
Info : device id = 0x10006452
|
||||
Warn : Cannot identify target as a STM32 family.
|
||||
Error: auto_probe failed
|
||||
embedded:startup.tcl:487: Error: ** Programming Failed **
|
||||
in procedure 'program'
|
||||
in procedure 'program_error' called at file "embedded:startup.tcl", line 543
|
||||
at file "embedded:startup.tcl", line 487
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
Compile and install a recent version of openocd from source. The latest official release (0.10.0 as of Nov 2020) doesn't support the STM32F722 yet.
|
||||
```
|
||||
sudo apt-get install libtool libusb-1.0
|
||||
git clone https://git.code.sf.net/p/openocd/code openocd
|
||||
cd openocd/
|
||||
./bootstrap
|
||||
./configure --enable-stlink
|
||||
make
|
||||
sudo make install
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
All *.md files in the `docs/` directory of the master branch are served up by GitHub Pages on [this domain](https://docs.odriverobotics.com).
|
||||
|
||||
* Theme: [minimal](https://github.com/pages-themes/minimal) by [orderedlist](https://github.com/orderedlist)
|
||||
* HTML layout: `docs/_layouts/default.html`
|
||||
* CSS style: `docs/assets/css/styles.scss`
|
||||
* Site index: `docs/_data/index.yaml`
|
||||
|
||||
To run the docs server locally:
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
gem install bundler # The gem command typically comes with a Ruby installation
|
||||
#export PATH="$PATH:~/.gem/ruby/2.7.0/bin" # or similar (depends on OS)
|
||||
rm Gemfile.lock # only if below commands cause trouble
|
||||
bundle config path ruby-bundle
|
||||
bundle install
|
||||
mkdir -p _api _includes
|
||||
python ../Firmware/interface_generator_stub.py --definitions ../Firmware/odrive-interface.yaml --template _layouts/api_documentation_template.j2 --outputs _api/'#'.md && python ../Firmware/interface_generator_stub.py --definitions ../Firmware/odrive-interface.yaml --template _layouts/api_index_template.j2 --output _includes/apiindex.html
|
||||
bundle exec jekyll serve --incremental --host=0.0.0.0
|
||||
```
|
||||
|
||||
On Ubuntu 18.04, prerequisites are: `ruby ruby-dev zlib1g-dev`.
|
||||
|
||||
## Modifying libfibre
|
||||
|
||||
If you need to modify libfibre add `CONFIG_BUILD_LIBFIBRE=true` to your tup.config and rerun `make`. After this you can start `odrivetool` (on your local PC) and it will use the updated libfibre.
|
||||
|
||||
To cross-compile libfibre for the Raspberry Pi, run `make libfibre-linux-armhf` or `make libfibre-all`. This will require a docker container. See [fibre-cpp readme](../Firmware/fibre-cpp/README.md) for details.
|
||||
|
||||
docker run -it -v "$(pwd)":/build -v /tmp/build:/build/build -w /build fibre-compiler configs/linux-armhf.config
|
||||
|
||||
If you're satisfied with the changes don't forget to generate binaries for all
|
||||
supported systems using `make libfibre-all`.
|
||||
|
||||
## Releases
|
||||
|
||||
We use GitHub Releases to provide firmware releases.
|
||||
|
||||
1. Cut off the changelog to reflect the new release
|
||||
2. Merge the release candidate into master.
|
||||
3. Push a (lightweight) tag to the master branch. Follow the existing naming convention.
|
||||
4. If you changed something in libfibre, regenerate the binaries using `make libfibre-all`. See [Modifying libfibre](#modifying-libfibre) for details.
|
||||
5. Push the python tools to PyPI (see setup.py for details).
|
||||
6. Edit the release on GitHub to add a title and description (copy&paste from changelog).
|
||||
|
||||
## Other code maintenance notes
|
||||
The cortex M4F processor has hardware single precision float unit. However double precision operations are not accelerated, and hence should be avoided. The following regex is helpful for cleaning out double constants:
|
||||
find: `([-+]?[0-9]+\.[0-9]+(?:[eE][-+]?[0-9]+)?)([^f0-9e])`
|
||||
replace: `\1f\2`
|
||||
|
||||
<br><br>
|
||||
|
||||
## Notes for Contributors
|
||||
In general the project uses the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html), with a few exceptions:
|
||||
|
||||
- The default indentation is 4 spaces.
|
||||
- The 80 character limit is not very strictly enforced, merely encouraged.
|
||||
- The file extensions *.cpp and *.hpp are used instead of *.cc and *.h.
|
||||
|
||||
Your help is welcome! However before you start working on a feature/change that will take you a non-negligible amount of time and that you plan to upstream please discuss your plans with us on GitHub or Discord. This will ensure that your implementation is in line with the direction that ODrive is going.
|
||||
|
||||
When filing a PR please go through this checklist:
|
||||
|
||||
- Make sure you adhere to the same coding style that we use (see note above).
|
||||
- Update CHANGELOG.md.
|
||||
- If you removed/moved/renamed things in `odrive-interface.yaml` make sure to add corresponding bullet points tp the "API migration notes" section in the changelog. Use git to compare against the `devel` branch.
|
||||
- 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 `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 `odrive-interface.yaml`, make sure you update [enums.py](../tools/odrive/enums.py) and [ODriveEnums.h](../Arduino/ODriveArduino/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.
|
||||
210
docs/encoders.md
210
docs/encoders.md
@@ -1,210 +0,0 @@
|
||||
# Encoders
|
||||
|
||||
## Known and Supported Encoders
|
||||
Be sure to read the [ODrive Encoder Guide](https://docs.google.com/spreadsheets/d/1OBDwYrBb5zUPZLrhL98ezZbg94tUsZcdTuwiVNgVqpU).
|
||||
|
||||
## Encoder Calibration
|
||||
All encoder types supported by ODrive require that you do some sort of encoder calibration. This requires the following:
|
||||
* Selecting an encoder and mounting it to your motor
|
||||
* Choosing an interface (e.g., AB, ABI or SPI)
|
||||
* Connecting the pins to the odrive
|
||||
* Loading the correct odrive firmware (the default will work in many cases)
|
||||
* Motor calibration
|
||||
* Saving the settings in the odrive for correct bootup
|
||||
|
||||
### Encoder without index signal
|
||||
During encoder offset calibration the rotor must be allowed to rotate without any biased load during startup. That means mass and weak friction loads are fine, but gravity or spring loads are not okay.
|
||||
|
||||
In the `odrivetool`, type `<axis>.requested_state = AXIS_STATE_ENCODER_OFFSET_CALIBRATION` <kbd>Enter</kbd>.
|
||||
|
||||
To verify everything went well, check the following variables:
|
||||
|
||||
* `<axis>.error` should be 0.
|
||||
* `<axis>.encoder.config.phase_offset` - This should print a number, like -326 or 1364.
|
||||
* `<axis>.encoder.config.direction` - This should print 1 or -1.
|
||||
|
||||
### Encoder with index signal
|
||||
If you have an encoder with an index (Z) signal, you can avoid doing the offset calibration on every startup, and instead use the index signal to re-sync the encoder to a stored calibration.
|
||||
|
||||
Below are the steps to do the one-time calibration and configuration. Note that you can follow these steps with one motor at a time, or all motors together, as you wish.
|
||||
|
||||
* Since you will only do this once, it is recommended that you mechanically disengage the motor from anything other than the encoder, so that it can spin freely.
|
||||
* Set `<axis>.encoder.config.use_index` to `True`.
|
||||
* Run `<axis>.requested_state = AXIS_STATE_ENCODER_INDEX_SEARCH`. This will make the motor turn in one direction until it finds the encoder index.
|
||||
* Follow the calibration instructions for an [encoder without index signal](#encoder-without-index-signal).
|
||||
* Set `<axis>.encoder.config.pre_calibrated` to `True` to confirm that the offset is valid with respect to the index pulse.
|
||||
* If you would like to search for the index at startup, set `<axis>.config.startup_encoder_index_search` to `True`.
|
||||
* If you'd rather do it manually, just run `<axis>.requested_state = AXIS_STATE_ENCODER_INDEX_SEARCH` on every bootup.
|
||||
* If you are looking to start your machine as quickly as possible on bootup, also set `<axis>.motor.config.pre_calibrated` to `True` to save the current motor calibration and avoid doing it again on bootup.
|
||||
* Save the configuration by typing `<odrv>.save_configuration()` <kbd>Enter</kbd>.
|
||||
|
||||
That's it, now on every reboot the motor will turn in one direction until it finds the encoder index.
|
||||
|
||||
* If your motor has problems reaching the index location due to the mechanical load, you can increase `<axis>.motor.config.calibration_current`.
|
||||
|
||||
### Reversing index search
|
||||
Sometimes you would like the index search to only happen in a particular direction (the reverse of the default). Instead of swapping the motor leads, you can ensure that the following three values are negative:
|
||||
* `<axis0>.config.calibration_lockin.vel`
|
||||
* `<axis0>.config.calibration_lockin.accel`
|
||||
* `<axis0>.config.calibration_lockin.ramp_distance`
|
||||
|
||||
|
||||
*IMPORTANT:* Your motor should find the same rotational position when the ODrive performs an index search if the index signal is working properly. This means that the motor should spin, and stop at the same position if you have set <axis>.config.startup_encoder_index_search so the search starts on reboot, or you if call the command:<axis>.requested_state = AXIS_STATE_ENCODER_INDEX_SEARCH after reboot. You can test this. Send the reboot() command, and while it's rebooting turn your motor, then make sure the motor returns back to the correct position each time when it comes out of reboot. Try this procedure a couple of times to be sure.
|
||||
|
||||
### Hall Effect Encoders
|
||||
Hall effect encoders can also be used with ODrive. The encoder CPR should be set to `6 * <# of motor pole pairs>`. Due to the low resolution of hall effect encoders compared to other types of encoders, low speed performance will be worse than other encoder types.
|
||||
|
||||
When the encoder mode is set to hall feedback, the pinout on the encoder port is as follows:
|
||||
|
||||
| Label on ODrive | Hall feedback |
|
||||
|-----------------|---------------|
|
||||
| A | Hall A |
|
||||
| B | Hall B |
|
||||
| Z | Hall C |
|
||||
|
||||
To use hall effect encoders, the calibration sequence is different than incremental or absolute encoders. You must first run `AXIS_STATE_ENCODER_HALL_POLARITY_CALIBRATION` before `AXIS_STATE_ENCODER_OFFSET_CALIBRATION` The hall polarity calibration will automatically determine the order and polarity of the hall signals. When using `AXIS_STATE_FULL_CALIBRATION_SEQUENCE`, these steps are automatically used if the encoder is set to hall mode.
|
||||
|
||||
### Startup sequence notes
|
||||
The following are variables that MUST be set up for your encoder configuration. Your values will vary depending on your encoder:
|
||||
|
||||
* `<axis>.encoder.config.cpr = 8192`
|
||||
* `<axis>.encoder.config.mode = ENCODER_MODE_INCREMENTAL`
|
||||
|
||||
The following are examples of values that can impact the success of calibration. These are not all of the variables you have to set for startup. Only change these when you understand why they are needed; your values will vary depending on your setup:
|
||||
* `<axis>.motor.config.motor_type = MOTOR_TYPE_HIGH_CURRENT` The type of motor you have. Valid choices are high current or gimbal.
|
||||
* `<axis>.encoder.config.calib_range = 0.05` Helps to relax the accuracy of encoder counts during calibration
|
||||
* `<axis>.motor.config.calibration_current = 10.0` The motor current used for calibration. For large motors, this value can be increased to overcome friction and cogging.
|
||||
* `<axis>.motor.config.resistance_calib_max_voltage = 12.0` Max motor voltage used for measuring motor resistance. For motor calibration, it must be possible for the motor current to reach the calibration current without the applied voltage exceeding this config setting.
|
||||
* `<axis>.controller.config.vel_limit = 5` [turn/s] low values result in the spinning motor stopping abruptly during calibration
|
||||
|
||||
Lots of other values can get you. It's a process. Thankfully there are a lot of good people that will help you debug calibration problems.
|
||||
|
||||
If calibration works, congratulations.
|
||||
|
||||
Now try:
|
||||
* `<axis>.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL`
|
||||
* `<axis>.controller.input_vel = 1.5`
|
||||
let it loop a few times and then set:
|
||||
* `<axis>.requested_state = AXIS_STATE_IDLE`
|
||||
|
||||
Do you still have no errors? Awesome. Now, setup the motor and encoder to use known calibration values. This allows you to skip motor calibration and encoder offset calibration before using closed loop control. Note that this only works if you are using an absolute encoder or the encoder index input (see "Encoder with index signal" above).
|
||||
* `<axis>.encoder.config.pre_calibrated = True`
|
||||
* `<axis>.motor.config.pre_calibrated = True `
|
||||
|
||||
And see if ODrive agrees that the calibration worked by just running
|
||||
* `<axis>.encoder.config.pre_calibrated`
|
||||
|
||||
(using no "= True" ). Make sure that 'pre_calibrated' is in fact True.
|
||||
|
||||
Also, if you have calibrated and encoder.pre_calibrated is equal to true, and you had no errors so far, run this:
|
||||
* `odrv0.save_configuration()`
|
||||
* `odrv0.reboot()`
|
||||
|
||||
and now see if after a reboot you can run:
|
||||
* `<axis>.requested_state = AXIS_STATE_ENCODER_INDEX_SEARCH`
|
||||
|
||||
without getting errors.
|
||||
|
||||
## What happens if calibration fails
|
||||
There are subtle ways that encoder problems will impact your ODrive. For example, ODrive may not complete the calibrate sequence when you go to:
|
||||
* `<axis>.requested_state = AXIS_STATE_FULL_CALIBRATION_SEQUENCE`
|
||||
|
||||
Or, ODrive may complete the calibrate sequence after:
|
||||
* `<axis>.requested_state = AXIS_STATE_FULL_CALIBRATION_SEQUENCE`
|
||||
|
||||
but then it fails after you go to:
|
||||
* `<axis>.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL`
|
||||
|
||||
Or ODrive may just vibrate in an entertaining way. See:
|
||||
https://www.youtube.com/watch?v=gaRUmwvSyAs
|
||||
|
||||
## Encoder Testing
|
||||
There are things you can test to make sure your encoder is properly connected. `shadow_count` tracks encoder motion, even before the encoder or motor are calibrated. If your encoder is working, you should see this value change when you turn the motor.
|
||||
Run the command:
|
||||
* `<axis>.encoder.shadow_count `
|
||||
|
||||
and look at your value. Then turn your motor by hand and see if that value changes. Also, notice that the command:
|
||||
* `<axis>.encoder.config.cpr = 4000`
|
||||
|
||||
must reflect the number of counts ODrive receives after one complete turn of the motor. So use shadow_count to test if that is working properly.
|
||||
|
||||
You will probably never be able to properly debug if you have problems unless you use an oscilloscope. If you have one, try the following:
|
||||
Connect to the AB pins, see if you get square waves as you turn the motor.
|
||||
Connect to the I pin, see if you get a pulse on a complete rotation. Sometimes this is hard to see.
|
||||
|
||||
If you are using SPI, use a logic analyzer and connect to the CLK, MISO, and CS pins. Set a trigger for the CS pin and ensure that the encoder position is being sent and is increasing/decreasing as you spin the motor. There is extremely cheap hardware that is supported by [Sigrok](https://sigrok.org/) for protocol analysis.
|
||||
|
||||
|
||||
## Encoder Noise
|
||||
Noise is found in all circuits, life is just about figuring out if it is preventing your system from working. Lots of users have no problems with noise interfering with their ODrive operation, others will tell you "_I've been using the same encoder as you with no problems_". Power to 'em, that may be true, but it doesn't mean it will work for you. If you are concerned about noise, there are several possible sources:
|
||||
|
||||
* Importantly, encoder wires may be too close to motor wires, avoid overlap as much as possible
|
||||
* Long wires between encoder and ODrive
|
||||
* Use of ribbon cable
|
||||
|
||||
The following _might_ mitigate noise problems. Use shielded cable, or use twisted pairs, where one side of each twisted pair is tied to ground and the other side is tied to your signal. If you are using SPI, use a 20-50 ohm resistor in series on CLK, which is more susceptible noise.
|
||||
|
||||
If you are using an encoder with an index signal, another problem that has been encountered is noise on the Z input of ODrive. Symptoms for this problem include:
|
||||
* difficulty with requested_state = AXIS_STATE_FULL_CALIBRATION_SEQUENCE, where your calibration sequence may not complete
|
||||
* strange behavior after performing odrv0.save_configuration() and odrv0.reboot()
|
||||
* when performing an index_search, the motor does not return to the same position each time.
|
||||
One easy step that _might_ fix the noise on the Z input is to solder a 22nF-47nF capacitor to the Z pin and the GND pin on the underside of the ODrive board.
|
||||
|
||||
## Hall feedback pinout
|
||||
If position accuracy is not a concern, you can use A/B/C hall effect encoders for position feedback.
|
||||
|
||||
To use this mode, configure the corresponding encoder mode: `<encoder>.config.mode = ENCODER_MODE_HALL`. Configure the corresponding GPIOs as digital inputs:
|
||||
|
||||
For encoder 0:
|
||||
|
||||
<odrv>.config.gpio9_mode = GPIO_MODE_DIGITAL
|
||||
<odrv>.config.gpio10_mode = GPIO_MODE_DIGITAL
|
||||
<odrv>.config.gpio11_mode = GPIO_MODE_DIGITAL
|
||||
|
||||
For encoder 1:
|
||||
|
||||
<odrv>.config.gpio12_mode = GPIO_MODE_DIGITAL
|
||||
<odrv>.config.gpio13_mode = GPIO_MODE_DIGITAL
|
||||
<odrv>.config.gpio14_mode = GPIO_MODE_DIGITAL
|
||||
|
||||
In this mode, the pinout on the encoder port is as follows:
|
||||
|
||||
| Label on ODrive | Hall feedback |
|
||||
|-----------------|---------------|
|
||||
| A | Hall A |
|
||||
| B | Hall B |
|
||||
| Z | Hall C |
|
||||
|
||||
## SPI Encoders
|
||||
|
||||
Apart from (incremental) quadrature encoders, ODrive also supports absolute SPI encoders (since firmware v0.5). These usually measure an absolute angle. This means you don't need to repeat the encoder calibration after every ODrive reboot. Currently, the following modes are supported:
|
||||
|
||||
* **CUI protocol**: Compatible with the AMT23xx family (AMT232A, AMT232B, AMT233A, AMT233B).
|
||||
* **AMS protocol**: Compatible with AS5047P and AS5048A.
|
||||
|
||||
Some of these chips come with evaluation boards that can simplify mounting the chips to your motor. For our purposes if you are using an evaluation board you should select the settings for 3.3v.
|
||||
|
||||
**Note:** The AMT23x family has a hardware bug that causes them to not properly tristate the MISO line. To use them with ODrive, there are two workarounds. One is to sequence power to the encoder a second or two after the ODrive recieves power. This allows 1 encoder to be used without issue. Another solution is to add a tristate buffer, such as the 74AHC1G125SE, on the MISO line between the ODrive and each AMT23x encoder. Tie the enable pin on the buffer to the CS line for the respective encoder. This allows for more than one AMT23x encoder, or one AMT23x and another SPI encoder, to be used at the same time.
|
||||
|
||||
1. Connect the encoder to the ODrive's SPI interface:
|
||||
|
||||
- The encoder's SCK, MISO (aka "DATA" on CUI encoders), MOSI (if present on the encoder), GND and 3.3V should connect to the ODrive pins with the same label. If you want to save a wire with AMS encoders, you can also connect the encoder's MOSI to the encoder's VDD instead.
|
||||
- The encoder's Chip Select (aka nCS/CSn) can be connected to any of the ODrive's GPIOs (caution: GPIOs 1 and 2 are usually used by UART).
|
||||
|
||||
If you are having calibration problems, make sure that your magnet is centered on the axis of rotation on the motor. Some users report that this has a significant impact on calibration. Also make sure that your magnet height is within range of the spec sheet.
|
||||
|
||||
2. In `odrivetool`, run:
|
||||
|
||||
<axis>.encoder.config.abs_spi_cs_gpio_pin = 4 # or which ever GPIO pin you choose
|
||||
<axis>.encoder.config.mode = ENCODER_MODE_SPI_ABS_CUI # or ENCODER_MODE_SPI_ABS_AMS
|
||||
<axis>.encoder.config.cpr = 2**14 # or 2**12 for AMT232A and AMT233A
|
||||
<odrv>.save_configuration()
|
||||
<odrv>.reboot()
|
||||
|
||||
3. Run the [offset calibration](#encoder-without-index-signal) and then save the calibration with `<odrv>.save_configuration()`.
|
||||
The next time you reboot, the encoder should be immediately ready.
|
||||
|
||||
Sometimes the encoder takes longer than the ODrive to start, in which case you need to clear the errors after every restart.
|
||||
|
||||
If you are having calibration problems - make sure your magnet is centered on the axis of rotation on the motor, some users report this has a significant impact on calibration. Also make sure your magnet height is within range of the spec sheet.
|
||||
|
||||
142
docs/endstops.md
142
docs/endstops.md
@@ -1,142 +0,0 @@
|
||||
# Endstops and Homing
|
||||
|
||||
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. The process of finding your machine's zero position is known as `homing`.
|
||||
|
||||
ODrive supports the use of its GPIO pins to connect to phyiscal limit switches or other sensors that can serve as endstops. Before you can home your machine, you must be able to adequately control your motor in `AXIS_STATE_CLOSED_LOOP_CONTROL`.
|
||||
|
||||
---
|
||||
|
||||
## Endstop Configuration
|
||||
Each axis supports two endstops: `min_endstop` and `max_endstop`. For each endstop, the following properties are accessible through `odrivetool`:
|
||||
|
||||
Name | Type | Default
|
||||
--- | -- | --
|
||||
gpio_num | int | 0
|
||||
offset | float | 0.0
|
||||
debounce_ms | float | 50.0
|
||||
enabled | boolean | false
|
||||
is_active_high | boolean | false
|
||||
|
||||
### gpio_num
|
||||
The GPIO pin number, according to the silkscreen labels on ODrive. Set with these commands:
|
||||
```
|
||||
<odrv>.<axis>.max_endstop.config.gpio_num = <1, 2, 3, 4, 5, 6, 7, 8>
|
||||
<odrv>.<axis>.min_endstop.config.gpio_num = <1, 2, 3, 4, 5, 6, 7, 8>
|
||||
```
|
||||
|
||||
### enabled
|
||||
Enables/disables detection of the endstop. If disabled, homing and e-stop cannot take place. Set with:
|
||||
```
|
||||
<odrv>.<axis>.max_endstop.config.enabled = <True, False>
|
||||
<odrv>.<axis>.min_endstop.config.enabled = <True, False>
|
||||
```
|
||||
|
||||
### offset
|
||||
This is the position of the endstops on the relevant axis, in turns. For example, if you want a position command of `0` to represent a position 3 turns away from the endstop, the offset would be `-3.0` (because the endstop is located at axis position `-3.0`).
|
||||
|
||||
```
|
||||
<odrv>.<axis>.min_endstop.config.offset = <int>
|
||||
```
|
||||
|
||||
This setting is only used for homing. Only the offset of the `min_endstop` is used.
|
||||
|
||||
### debounce_ms
|
||||
The debouncing time for this endstop. Most switches exhibit some sort of bounce, and this setting will help prevent the switch from triggering repeatedly. It works for both HIGH and LOW transitions, regardless of the setting of `is_active_high`. Debouncing is a good practice for digital inputs, read up on it [here](https://en.wikipedia.org/wiki/Switch). `debounce_ms` has units of miliseconds.
|
||||
|
||||
```
|
||||
<odrv>.<axis>.max_endstop.config.debounce_ms = <Float>
|
||||
<odrv>.<axis>.min_endstop.config.debounce_ms = <Float>
|
||||
```
|
||||
|
||||
### is_active_high
|
||||
This is how you configure the endstop to be either "NPN" or "PNP". An "NPN" configuration would be `is_active_high = False` whereas a PNP configuration is `is_active_high = True`. Refer to the following table for more information:
|
||||
|
||||
Typically configuration **1** or **3** is preferred when using mechanical switches as the most common failure mode leaves the switch open.
|
||||
|
||||
### GPIO configuration
|
||||
The GPIOs that are used for the endstops need to be configured according to the diagram below.
|
||||
|
||||
Assuming your endstop is connected to GPIO X:
|
||||
|
||||
- Configuration 1, 2: `<odrv>.config.gpioX_mode = GPIO_MODE_DIGITAL_PULL_DOWN`
|
||||
- Configuration 3, 4: `<odrv>.config.gpioX_mode = GPIO_MODE_DIGITAL_PULL_UP`
|
||||
|
||||
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
If we want to configure a 3D printer-style (configuration 4) minimum endstop for homing on GPIO 5 and we want our motor to move away from the endstop about a quarter turn, we would set:
|
||||
|
||||
```
|
||||
<odrv>.config.gpio5_mode = GPIO_MODE_DIGITAL
|
||||
<odrv>.<axis>.min_endstop.config.gpio_num = 5
|
||||
<odrv>.<axis>.min_endstop.config.is_active_high = False
|
||||
<odrv>.<axis>.min_endstop.config.offset = -0.25
|
||||
<odrv>.<axis>.min_endstop.config.enabled = True
|
||||
<odrv>.config.gpio5_mode = GPIO_MODE_DIGITAL_PULL_UP
|
||||
```
|
||||
|
||||
### Testing The Endstops
|
||||
Once the endstops are configured you can test your endstops for correct functionality. Try activating your endstops and check the states of these variables through odrivetool:
|
||||
|
||||
```
|
||||
<odrv>.<axis>.max_endstop.endstop_state
|
||||
<odrv>.<axis>.min_endstop.endstop_state
|
||||
```
|
||||
|
||||
A state of `True` means the switch is pressed. A state of `False` means the switch is NOT pressed. As simple as that. Give it a try. Click your switches, or put a magnet on your hall switch and see if the states change.
|
||||
|
||||
After testing, don't forget to save and reboot:
|
||||
```
|
||||
<odrv>.save_configuration()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Homing Configuration
|
||||
There is one additional configuration parameter in `controller.config` specifically for the homing process:
|
||||
|
||||
Name | Type | Default
|
||||
--- | -- | --
|
||||
homing_speed | float | 0.25f
|
||||
|
||||
`homing_speed` is the axis travel speed during homing, in [turns/second]. If you are using SPI based encoders and the axis is homing in the wrong direction, you can enter a negative value for the homing speed and a negative value for the minimum endstop offset.
|
||||
|
||||
```
|
||||
# Set the homing speed to 0.25 turns / sec
|
||||
odrv0.axis0.controller.config.homing_speed = 0.25
|
||||
```
|
||||
|
||||
### Performing the Homing Sequence
|
||||
Homing is possible once the ODrive has closed-loop control over the axis. To trigger homing, we must enter `AXIS_STATE_HOMING`. This starts the homing sequence, which works as follows:
|
||||
|
||||
1. The axis switches to `INPUT_MODE_VEL_RAMP`
|
||||
2. The axis ramps up to `homing_speed` in the direction of `min_endstop`
|
||||
3. The axis presses the `min_endstop`
|
||||
4. The axis switches to `INPUT_MODE_TRAP_TRAJ`
|
||||
5. The axis moves to the home position in a controlled manner
|
||||
|
||||
It requires quite a few settings in addition to the endstop settings:
|
||||
|
||||
```
|
||||
<odrv>.<axis>.controller.config.vel_ramp_rate
|
||||
<odrv>.<axis>.trap_traj.config.vel_limit
|
||||
<odrv>.<axis>.trap_traj.config.accel_limit
|
||||
<odrv>.<axis>.trap_traj.config.decel_limit
|
||||
```
|
||||
|
||||
We realize this is a little excessive and we will work towards minimizing the setup, but this works well for smooth and reliable behaviour for now.
|
||||
|
||||
### Homing at Startup
|
||||
It is possible to configure the odrive to enter homing immediately after startup. To enable homing at startup, the following must be configured:
|
||||
|
||||
```
|
||||
<odrv>.<axis>.config.startup_homing = True
|
||||
```
|
||||
|
||||
## Additional endstop devices
|
||||
|
||||
In addition to phyiscal switches there are other options for wiring up your endstops - you will have to work out the details of connecting your device but here are some suggested approaches:
|
||||
|
||||
|
||||
@@ -49,8 +49,8 @@ class MethodDocumenter(Documenter):
|
||||
return [
|
||||
'',
|
||||
'.. py:method:: ' + method.name + '(' + in_str + ')' + out_str,
|
||||
*(['', ' ' + method.brief] if method.brief else []),
|
||||
*(['', ' ' + method.doc] if method.doc else []),
|
||||
*(['', *add_indent(method.brief.split('\n'))] if method.brief else []),
|
||||
*(['', *add_indent(method.doc.split('\n'))] if method.doc else []),
|
||||
'',
|
||||
*((' :param ' + registry.get_py_val_type_name(decl_ns_path, arg.type) + ' ' + arg.name + ':' + (' ' + arg.doc if arg.doc else '')) for arg in method.input_args),
|
||||
'',
|
||||
@@ -65,8 +65,8 @@ class AttributeDocumenter(Documenter):
|
||||
'',
|
||||
'.. py:attribute:: ' + attr.name,
|
||||
' :type: ' + registry.get_py_ref_type_name(decl_ns_path, attr.type),
|
||||
*(['', ' ' + attr.brief] if attr.brief else []),
|
||||
*(['', ' ' + attr.doc] if attr.doc else []),
|
||||
*(['', *add_indent(attr.brief.split('\n'))] if attr.brief else []),
|
||||
*(['', *add_indent(attr.doc.split('\n'))] if attr.doc else []),
|
||||
''
|
||||
]
|
||||
|
||||
@@ -197,6 +197,9 @@ class FibredocDirective(SphinxDirective):
|
||||
documenter = documenters[objtype]()
|
||||
|
||||
registry = self.env.app.fibre_registry
|
||||
|
||||
for file in self.config.fibre_interface_files:
|
||||
self.env.note_dependency(file)
|
||||
|
||||
decl_ns, obj = documenter.load_object(registry, self.arguments[0])
|
||||
lines = documenter.generate(registry, decl_ns.get_path()[:2], obj, self.options)
|
||||
|
||||
BIN
docs/favicon.ico
BIN
docs/favicon.ico
Binary file not shown.
|
Before Width: | Height: | Size: 2.3 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 45 KiB After Width: | Height: | Size: 45 KiB |
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 53 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 67 KiB After Width: | Height: | Size: 67 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 1.6 MiB After Width: | Height: | Size: 1.6 MiB |
|
Before Width: | Height: | Size: 14 KiB After Width: | Height: | Size: 14 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user