Skip to content

Commit 136cf75

Browse files
SparkFun-Documentation-TeamSparkFun-Documentation-Team
committed
Python and Java(FTC) software setup changes
1 parent d838d61 commit 136cf75

9 files changed

+468
-13
lines changed

‎docs/assets/img/android_studio.png

32.3 KB
Loading

‎docs/assets/img/hardware_config.png

88.2 KB
Loading

‎docs/contribute.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Contribute: Make an Augmentation!
2+
Spot an improvement opportunity? Feel free to contribute to our open-source design and documentation. <a href="https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/pulls" alt="Pull Requests"><img src="https://img.shields.io/github/issues-pr/sparkfun/https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor.svg" /></a>
3+
4+
5+
## :material-file-document-multiple:&nbsp;Improve our Documentation
6+
All of this documentation can be modified by you! Please help us make it better.
7+
8+
* These pages are contained in the [`docs` folder](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/tree/main/docs) of the [SparkFun Optical Tracking Odometry Sensor - PAA5160E1 (Qwiic) repository](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor).
9+
10+
### Submit a Correction
11+
12+
1. With a GitHub account, [fork this repository](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/fork).
13+
2. Add your corrections or improvements to the markdown file.
14+
3. File a pull request with your changes, and enjoy making the ~~words~~ ~~worlds~~ world a better place.
15+
* Once received, the documentation specialist will automatically be notified.
16+
* We will review your suggested improvements to make sure they are correct and fit within our documentation standards.
17+
18+
## :material-cog:&nbsp;Improve our Hardware Design
19+
All of our designs are open-source! Please help us make it better.
20+
21+
* Our board design files are contained in the [`Hardware` folder](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/tree/main/Hardware) of the [SparkFun Optical Tracking Odometry Sensor - PAA5160E1 (Qwiic) repository](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor).
22+
23+
1. With a GitHub account, [fork this repository](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/fork).
24+
2. Add your design augmentation(s)
25+
3. File a pull request with your changes, and enjoy making the ~~words~~ ~~worlds~~ world a better place.
26+
1. Once received, the engineer in charge of the original design will automatically be notified.
27+
2. We will review your suggested improvement(s) to verify that they are within our board design standards and meet our product design requirements.
28+
3. If approved, we will flag these changes for our next board revision. Congrats! 🍻
29+
30+
!!! info
31+
Even if your suggestion is accepted, these changes may not be immediately available for purchase. We may have to cycle through our current product inventory first.
32+
33+
34+
## Contributors&nbsp;:clap:
35+
Let's provide some recognition to the contributors for this project!
36+
37+
![GitHub Contributors Image](https://contrib.rocks/image?repo=sparkfun)
38+
<br>
39+
<a href="https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/pulls" alt="Pull Requests"><img src="https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor.svg" /></a>

‎docs/examples-Python.md

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
---
2+
icon: simple/python
3+
---
4+
5+
!!! attention
6+
7+
All of the examples require the user to enter a key into the serial monitor before the example starts, which triggers the IMU calibration.
8+
9+
!!! attention
10+
11+
The IMU on the Optical Tracking Odometry Sensor includes a gyroscope and accelerometer, which could have an offset. The OTOS performs a quick calibration when it powers up, but it is recommended to perform a more thorough calibration at the start of all your programs.
12+
13+
###Example 1: Basic Readings
14+
15+
This first example just does some basic measurements to make sure everything is hooked up correctly.
16+
17+
18+
<figure markdown>
19+
[![Optical Tracking Odometry Sensor Python Example 1](assets/img/){ width="600" }](assets/img/ "Click to enlarge")
20+
<figcaption markdown>Finding Example 1</figcaption>
21+
</figure>
22+
23+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Python file:
24+
25+
??? "Example 1 Python Code"
26+
```
27+
--8<-- "https://raw.githubusercontent.com/sparkfun/Qwiic_OTOS_Py/master/examples/qwiic_otos_ex1_basic_readings.py"
28+
```
29+
30+
31+
32+
33+
<figure markdown>
34+
[![Optical Tracking Odometry Sensor Python Example 1 Output](assets/img/){ width="600" }](assets/img/ "Click to enlarge")
35+
<figcaption markdown>Example 1 Output</figcaption>
36+
</figure>
37+
38+
Move the sensor around to see how the coordinates change!
39+
40+
41+
###Example 2: SetUnits
42+
43+
This example sets the desired units for linear and angular measurements. Can be either meters or inches for linear, and radians or degrees for angular. If not set, the default is inches and degrees. Note that this setting is not stored in the sensor, it's part of the library, so you need to set at the start of all your programs.
44+
45+
<!-- To find Example 2, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example2_SetUnits**: -->
46+
47+
48+
<figure markdown>
49+
[![Optical Tracking Odometry Sensor Arduino Example 2](assets/img/Arduino_Example_2_Menu.jpg){ width="600" }](assets/img/Arduino_Example_2_Menu.jpg "Click to enlarge")
50+
<figcaption markdown>Finding Example 2</figcaption>
51+
</figure>
52+
53+
Alternatively, you can expand the link below and copy and paste the code into a shiny Python file:
54+
55+
56+
57+
??? "Example 2 Python Code"
58+
```
59+
--8<-- "https://raw.githubusercontent.com/sparkfun/Qwiic_OTOS_Py/master/examples/qwiic_otos_ex2_set_units.py"
60+
```
61+
62+
Notice the following code snippet - this is the section of code that allows you to choose your units:
63+
64+
<figure markdown>
65+
[![Optical Tracking Odometry Sensor Arduino Example 2 Code Snippet](assets/img/Arduino_Example_2_CodeSnippet.jpg){ width="600" }](assets/img/Arduino_Example_2_CodeSnippet.jpg "Click to enlarge")
66+
<figcaption markdown>Example 2 Code To Change Units </figcaption>
67+
</figure>
68+
69+
70+
Make sure you've selected the correct board and port in the Tools menu and then hit the upload button. Once the code has finished uploading, go ahead and open a [Serial Monitor](https://learn.sparkfun.com/tutorials/terminal-basics). You should see something similar to the following.
71+
72+
<figure markdown>
73+
[![Optical Tracking Odometry Sensor Arduino Example 2](assets/img/Arduino_Example_2_Output.jpg){ width="600" }](assets/img/Arduino_Example_2_Output.jpg "Click to enlarge")
74+
<figcaption markdown>Example 2 Output</figcaption>
75+
</figure>
76+
77+
78+
###Example 3: Calibration
79+
80+
!!! warning
81+
82+
As of firmware version 1.0, these calibration values will be lost after a power cycle, so you will need to set them each time you power up the sensor.
83+
84+
85+
The data from the OTOS will likely have minor scaling errors that can be calibrated out. This is especially important for the angular scalar, because an incorrect angle measurement causes the linear measurements to be rotated by the wrong angle in the firmware, which can lead to very inaccurate tracking.
86+
87+
<!-- To find Example 3, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example3_Calibration**: -->
88+
89+
90+
<figure markdown>
91+
[![Optical Tracking Odometry Sensor Arduino Example 3](assets/img/Arduino_Example_3_Menu.jpg){ width="600" }](assets/img/Arduino_Example_3_Menu.jpg "Click to enlarge")
92+
<figcaption markdown>Finding Example 3</figcaption>
93+
</figure>
94+
95+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Python file:
96+
97+
98+
99+
??? "Example 3 Python Code"
100+
```
101+
--8<-- "https://raw.githubusercontent.com/sparkfun/Qwiic_OTOS_Py/master/examples/qwiic_otos_ex3_calibration.py"
102+
```
103+
104+
105+
106+
Make sure you've selected the correct board and port in the Tools menu and then hit the upload button. Once the code has finished uploading, go ahead and open a [Serial Monitor](https://learn.sparkfun.com/tutorials/terminal-basics).
107+
108+
Calibrating your bot requires you to move it around a bit. First, set both scalars to 1.0, then calibrate the angular scalar, then the linear scalar.
109+
110+
To calibrate the angular scalar, spin the robot by multiple rotations (eg. 10) to get a precise error, then set the scalar to the inverse of the error. Remember that the angle wraps from -180 to 180 degrees, so for example, if after 10 rotations counterclockwise(positive rotation), the sensor reports -15 degrees, the required scalar would be 3600/3585 = 1.004.
111+
112+
<figure markdown>
113+
[![Rotating the Optical Tracking Odometry Sensor](assets/img/SEN-24904-XRP-Rotation.jpg){ width="600" }](assets/img/SEN-24904-XRP-Rotation.jpg "Click to enlarge")
114+
<figcaption markdown>Rotating the Optical Tracking Odometry Sensor</figcaption>
115+
</figure>
116+
117+
118+
To calibrate the linear scalar, move the robot a known distance and measure the error; do this multiple times at multiple speeds to get an average, then set the linear scalar to the inverse of the error. For example, if you move the robot 100 inches and the sensor reports 103 inches, set the linear scalar to 100/103 = 0.971.
119+
120+
121+
<figure markdown>
122+
[![Moving the Optical Tracking Odometry Sensor](assets/img/SEN-24904-XRP-Distance.jpg){ width="600" }](assets/img/SEN-24904-XRP-Distance.jpg "Click to enlarge")
123+
<figcaption markdown>Moving the Optical Tracking Odometry Sensor</figcaption>
124+
</figure>
125+
126+
127+
128+
129+
###Example 4: SetOffsetAndPosition
130+
131+
This example shows how to set the offset for the sensor relative to the center of the robot. The units default to inches and degrees, but if you want to use different units, make sure you specify them before setting the offset. Without setting the offset, the OTOS will report the coordinates of itself. If the offset is set, the OTOS will instead report the coordinates of the center of your robot.
132+
133+
Note that the OTOS typically starts tracking from the origin, but if your robot starts at some other location, or you have another source of location information from another sensor that's more accurate, you can send the current location to the OTOS and it will continue tracking from there.
134+
135+
!!! warning
136+
137+
As of firmware version 1.0, these values will be lost after a power cycle, so you will need to set them each time you power up the sensor.
138+
139+
140+
To find Example 4, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example4_SetOffsetAndPosition**:
141+
142+
143+
<figure markdown>
144+
[![Optical Tracking Odometry Sensor Arduino Example 4](assets/img/Arduino_Example_4_Menu.jpg){ width="600" }](assets/img/Arduino_Example_4_Menu.jpg "Click to enlarge")
145+
<figcaption markdown>Finding Example 4</figcaption>
146+
</figure>
147+
148+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch:
149+
150+
151+
152+
??? "Example 4 Arduino Code"
153+
```
154+
--8<-- "https://raw.githubusercontent.com/sparkfun/SparkFun_Qwiic_OTOS_Arduino_Library/main/examples/Example4_SetOffsetAndPosition/Example4_SetOffsetAndPosition.ino"
155+
```
156+
157+
158+
If the sensor is mounted 5 inches to the left (negative X) and 10 inches forward (positive Y) of the center of the robot, and mounted 90 degrees clockwise (negative rotation) from the robot's orientation, the offset would be {-5, 10, -90}. These can be any value, even the angle can be tweaked slightly to compensate for imperfect mounting (eg. 1.3 degrees).
159+
160+
<figure markdown>
161+
[![The X, Y, and Angular Offset of the Optical Tracking Sensor](assets/img/SEN-24904-XRP-XY-Offset.jpg){ width="600" }](assets/img/SEN-24904-XRP-XY-Offset.jpg "Click to enlarge")
162+
<figcaption markdown>The X, Y, and Angular Offset of the Optical Tracking Sensor</figcaption>
163+
</figure>
164+
165+
166+
These four examples cover the basics - there are more examples to explore in the library!
167+
168+
169+
170+
<!--
171+
###Example 5: VelocityAndAcceleration
172+
173+
This example prints out the velocity and acceleration of the bot as it moves.
174+
175+
176+
To find Example 5, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example5_VelocityAndAcceleration**:
177+
178+
179+
<figure markdown>
180+
[![Optical Tracking Odometry Sensor Arduino Example 5](assets/img/Arduino_Example_5_Menu.jpg){ width="600" }](assets/img/Arduino_Example_5_Menu.jpg "Click to enlarge")
181+
<figcaption markdown>Finding Example 5</figcaption>
182+
</figure>
183+
184+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch:
185+
186+
187+
188+
??? "Example 5 Arduino Code"
189+
```
190+
--8<-- ""
191+
```
192+
193+
https://raw.githubusercontent.com/sparkfun/SparkFun_Qwiic_OTOS_Arduino_Library/v1.0.0/examples/Example5_VelocityAndAcceleration/Example5_VelocityAndAcceleration.ino
194+
195+
196+
197+
###Example 6: StandardDeviation
198+
199+
This example reads the standard deviation of the tracking. Note that these values are just the square root of the diagonal elements of the covariance matrices of the Kalman filters used in the firmware of the OTOS and not actual tracking error data.
200+
201+
!!! warning
202+
203+
THESE VALUES DO NOT REPRESENT THE ACTUAL TRACKING ERROR! These are statistical quantities that assume a correct model of the system, but there could be unmodelled error sources that cause the physical error to become larger than these statistical error (eg. improper calibration, or rotating the OTOS to not be flat against the tracking surface). These are provided primarily for anyone wanting to perform sensor fusion with additional sensors, but they can be used to at least "get an idea" of the quality of the accuracy.
204+
205+
206+
207+
To find Example 6, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example6_StandardDeviation**:
208+
209+
210+
<figure markdown>
211+
[![Optical Tracking Odometry Sensor Arduino Example 6](assets/img/Arduino_Example_6_Menu.jpg){ width="600" }](assets/img/Arduino_Example_6_Menu.jpg "Click to enlarge")
212+
<figcaption markdown>Finding Example 6</figcaption>
213+
</figure>
214+
215+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch:
216+
217+
218+
219+
??? "Example 6 Arduino Code"
220+
```
221+
--8<-- ""
222+
```
223+
224+
https://raw.githubusercontent.com/sparkfun/SparkFun_Qwiic_OTOS_Arduino_Library/v1.0.0/examples/Example6_StandardDeviation/Example6_StandardDeviation.ino
225+
226+
227+
228+
229+
###Example 7: GetVersion
230+
231+
This should be fairly self explanatory. This example gets the current hardware and firmware version of the board.
232+
233+
234+
To find Example 7, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example7_GetVersion**:
235+
236+
237+
<figure markdown>
238+
[![Optical Tracking Odometry Sensor Arduino Example 7](assets/img/Arduino_Example_7_Menu.jpg){ width="600" }](assets/img/Arduino_Example_7_Menu.jpg "Click to enlarge")
239+
<figcaption markdown>Finding Example 7</figcaption>
240+
</figure>
241+
242+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch:
243+
244+
??? "Example 7 Arduino Code"
245+
```
246+
--8<-- ""
247+
```
248+
https://raw.githubusercontent.com/sparkfun/SparkFun_Qwiic_OTOS_Arduino_Library/v1.0.0/examples/Example7_GetVersion/Example7_GetVersion.ino
249+
250+
251+
Make sure you've selected the correct board and port in the Tools menu and then hit the upload button. Once the code has finished uploading, go ahead and open a [Serial Monitor](https://learn.sparkfun.com/tutorials/terminal-basics). You should see something similar to the following:
252+
253+
<figure markdown>
254+
[![Optical Tracking Odometry Sensor Arduino Example 7 Output](assets/img/Arduino_Example_7_Output.jpg){ width="600" }](assets/img/Arduino_Example_7_Output.jpg "Click to enlarge")
255+
<figcaption markdown>Example 7 Output</figcaption>
256+
</figure>
257+
258+
259+
260+
###Example 8: SelfTest
261+
262+
Again, this should be self explanatory. This example tests the basics to make sure everything is working as expected.
263+
264+
To find Example 8, go to **File** > **Examples** > **SparkFun Qwiic OTOS** > **Example8_SelfTest**:
265+
266+
267+
<figure markdown>
268+
[![Optical Tracking Odometry Sensor Arduino Example 8](assets/img/Arduino_Example_8_Menu.jpg){ width="600" }](assets/img/Arduino_Example_8_Menu.jpg "Click to enlarge")
269+
<figcaption markdown>Finding Example 8</figcaption>
270+
</figure>
271+
272+
Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch:
273+
274+
275+
276+
??? "Example 8 Arduino Code"
277+
```
278+
--8<-- ""
279+
```
280+
<!--
281+
https://raw.githubusercontent.com/sparkfun/SparkFun_Qwiic_OTOS_Arduino_Library/v1.0.0/examples/Example8_SelfTest/Example8_SelfTest.ino
282+
-->
283+
284+
285+

‎docs/file_issue.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Did we make a mistake?
2+
3+
Spot something wrong? Please let us know. <a href="https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/issues" alt="Issues"><img src="https://img.shields.io/github/issues/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor.svg" /></a>
4+
5+
!!! attention
6+
This is not where customers should seek assistance on a product. If you require technical assistance or have questions about a product that is not working as expected, please head over to the [SparkFun Technical Assistance](https://www.sparkfun.com/technical_assistance) page for some initial troubleshooting.
7+
<center>
8+
[SparkFun Technical Assistance Page](https://www.sparkfun.com/technical_assistance){ .md-button .md-button--primary }
9+
</center>
10+
11+
If you can't find what you need there, you'll need a [Forum Account](https://forum.sparkfun.com/ucp.php?mode=register) to search product forums and post questions.
12+
13+
## Discrepancies in the Documentation
14+
15+
All of this documentation can be modified by you! Please help us make it better.
16+
17+
* The documentation files for these pages are contained in the [`docs` folder](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/tree/main/docs) of the [SparkFun Optical Tracking Odometry Sensor - PAA5160E1 (Qwiic)](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor) repository.
18+
19+
### Spot something wrong?
20+
If a section of the documentation is incorrect, please [open an issue](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/issues) and let us know.
21+
22+
### Do you have a suggested correction?
23+
1. With a GitHub account, fork this repo
24+
2. Add your correction(s) or improvement(s) to the markdown file(s)
25+
3. File a pull request with your changes, and enjoy making the ~~words~~ ~~worlds~~ world a better place.
26+
* Once received, the documentation specialist will automatically be notified.
27+
* We will review your suggested improvement(s) to make sure they are correct and fit within our documentation standards.
28+
29+
## Problems in the Hardware Design
30+
31+
All of our designs are open-source! Please help us make it better.
32+
33+
* Our board design files are contained in the [`Hardware` folder](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/tree/main/Hardware) of the [SparkFun Optical Tracking Odometry Sensor - PAA5160E1 (Qwiic)](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor) repository.
34+
35+
### Does something not make sense?
36+
If part of the design is confusing, please [open an issue](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/issues) and let us know.
37+
38+
### Did we forget to include an important function of the board?
39+
* Please keep in mind that we may intentionally exclude certain functions of the board to meet our product design requirements. *(For example, our Qwiic Micro boards are intended to fit on a small board layout and only use I<sup>2</sup>C communication; therefore, we may not have the SPI and interrupt pins available for users.)*
40+
* If part of the board's functionality is missing, please [open an issue](https://github.com/sparkfun/SparkFun_Optical_Tracking_Odometry_Sensor/issues) and file a feature request.
41+
42+
### Do you wish to contribute directly to improving the board design?
43+
1. With a GitHub account, Fork this repo
44+
2. Add your design improvement(s)
45+
3. File a pull request with your changes, and enjoy making the ~~words~~ ~~worlds~~ world a better place.
46+
* Once received, the engineer in charge of the original design will automatically be notified.
47+
* We will review your suggested improvement(s), if they are within our board design standards and meet our product design requirements, we will flag these changes for our next board revision. *(Please note, that even if your suggestion is accepted, these changes may not be immediate. We may have to cycle through our current product inventory first.)*

0 commit comments

Comments
 (0)