Initial docs commit

Initial commit for product documentation

Author: santaimpersonator

Documentation/README.md

@@ -1,41 +1,48 @@
-SparkFun <PRODUCT NAME>
+SparkFun 3-Phase BLDC Motor Driver - TMC6300
 ========================================
 
-[![SparkFun Part Name](URL for picture of part)](URL for product on Sparkfun.com)
+[![SparkFun 3-Phase BLDC Motor Driver - TMC6300](https://cdn.sparkfun.com/assets/parts/2/1/6/9/6/21867-_SparkFun_Brushless_Motor_Drive-_01.jpg)](https://www.sparkfun.com/products/21867)
 
-[*SparkFun Part Name (SKU)*](URL for product on Sparkfun.com)
+[*SparkFun 3-Phase BLDC Motor Driver - TMC6300 (ROB-21867)*](https://www.sparkfun.com/products/21867)
+
+The TMC6300 from [ADI + Trinamic](https://www.trinamic.com/) is a powerful and easy to use three phase motor driver that was designed to control our [Brushless Gimbal Motor](https://www.sparkfun.com/products/20441). However, it can be used to control any 3-phase [BLDC](https://en.wikipedia.org/wiki/Brushless_DC_electric_motor "brushless DC") or [PMSM](https://en.wikipedia.org/wiki/Synchronous_motor#Permanent-magnet "permanent magnet synchronous motor") motor with up to 2A (1.4A<sub>RMS</sub>) of total drive current. Separate high-side and low-side control of the three half-bridges allows for incredible control of each phase of the [motor commutation](https://fab.cba.mit.edu/classes/865.21/topics/power_electronics/commutation/#bldc-commutation). The driver also provides temperature and short circuit protections; and a diagnostic output to indicate system faults. With a 1.8V regulated power output and an operating voltage down to 2V, the TMC6300 is suitable for low-power microcontroller and battery powered designs (min. 2 AA/NiMh cells, or 1-2 Li-Ion cells).
+
+Our board layout has been designed with the LEDs and labels facing up, IC down. This allows the thermal pad on the board to be access if cooling is required. Additionally, the breakout pins are specially aligned to fit perfectly onto a breadboard and hold the headers more perpendicular to facilitate assembly.
+
+Controlling 3-phase motors is not trivial and this board requires 6 PWM signals to fully control one motor. We've found the [*Arduino Simple Field Oriented Control*](https://docs.simplefoc.com/) library to work well with the board; however, there are some hadware limitations such as [supported microconrollers for `6PWM Mode`](https://docs.simplefoc.com/microcontrollers#supported-microcontrollers). With additional considerations, for integrating [position sensors](https://docs.simplefoc.com/position_sensors) into the feedback control loop.
 
-<Basic description of the part.>
 
 Repository Contents
 -------------------
 
-* **/Documentation** - Data sheets, additional product information
-* **/Enclosure** - Enclosure files 
-* **/Firmware** - Example code 
-* **/Hardware** - Eagle design files (.brd, .sch)
-* **/Libraries** - Libraries for use with the <PRODUCT NAME>
-* **/Production** - Production panel files (.brd)
-* **/Software** - Related software for the <PRODUCT NAME>
+* **[/docs](/docs/)** - Online documentation files
+    * [arduino_examples](/docs/arduino_examples/) - Example code
+    * [board_files](/docs/board_files/) - Files for the product design
+            * [Eagle design files](/docs/board_files/eagle_files.zip) (.zip)
+            * [Schematic](/docs/board_files/schematic.pdf) (.pdf)
+            * [Dimensions](/docs/board_files/dimensions.pdf) (.pdf)
+    * [component_documentation](/docs/component_documentation/) - Datasheets for hardware components
+    * [img/hookup_guide/](/docs/img/hookup_guide/) - Images for hookup guide documentation
+* **[/Hardware](/Hardware/)** - Eagle design files (.brd, .sch)
+
 
 Documentation
 --------------
-* **[Library](GitHub library URL)** - <LANGUAGE> library for the <PRODUCT NAME>.
-* **[Hookup Guide](Learn.SparkFun URL)** - Basic hookup guide for the <PRODUCT NAME>.
-* **[SparkFun Fritzing repo](https://github.com/sparkfun/Fritzing_Parts)** - Fritzing diagrams for SparkFun products.
-* **[SparkFun 3D Model repo](https://github.com/sparkfun/3D_Models)** - 3D models of SparkFun products. 
-* **[SparkFun Graphical Datasheets](https://github.com/sparkfun/Graphical_Datasheets)** -Graphical Datasheets for various SparkFun products.
+* **[Hookup Guide (mkdocs)](http://docs.sparkfun.com/SparkFun_Three_Phase_Motor_Driver-TMC6300/)** - Hookup guide for the USB-C Host Shield hosted by GitHub pages.
 
-Product Versions
+*Need to download or print our hookup guide?*
+
+* [Print *(Print to PDF)* from Single-Page View](http://docs.sparkfun.com/SparkFun_Three_Phase_Motor_Driver-TMC6300/hookup_guide/single_page)
+* [Download PDF](http://docs.sparkfun.com/SparkFun_Three_Phase_Motor_Driver-TMC6300/assets/board_files/hookup_guide.pdf) *(Beta - Mostly works, but some attributes may be broken.)*
+
+Product Variants
 ----------------
-* [Part SKU](part URL)- Basic part and short description here
-* [Retail part SKU](retail URL)- Retail packaging of standard description here
-* [Any other parts this repo covers](any other URLs) - Description of said parts
+* [ROB-21867](https://www.sparkfun.com/products/21867)- v1.0, Initial Release
 
 Version History
 ---------------
-* [vExxFxxZxxHxxLxxSxx](URL for tag specific to this version) - Description 
-* [vEyyFyyZyyHyyLyySyy](URL for tag specific to this version) - Description
+* [v01](https://github.com/sparkfun/SparkFun_Three_Phase_Motor_Driver-TMC6300/releases/tag/v10) - Initial Release
+
 
 License Information
 -------------------
@@ -44,10 +51,8 @@ This product is _**open source**_!
 
 Please review the LICENSE.md file for license information. 
 
-If you have any questions or concerns on licensing, please contact technical support on our [SparkFun forums](https://forum.sparkfun.com/viewforum.php?f=152).
+If you have any questions or concerns about licensing, please contact technical support on our [SparkFun forums](https://forum.sparkfun.com/viewforum.php?f=152).
 
 Distributed as-is; no warranty is given.
 
 - Your friends at SparkFun.
-
-_<COLLABORATION CREDIT>_

Enclosure/README.md

@@ -0,0 +1,3 @@
+docs directory
+====================
+This folder should contain the files for the product documentation

README.md

@@ -0,0 +1,35 @@
+// BLDC driver standalone example
+#include <SimpleFOC.h>
+
+// BLDC driver instance
+BLDCDriver6PWM driver = BLDCDriver6PWM(5, 6, 9,10, 3, 11);
+
+void setup() {
+
+  // pwm frequency to be used [Hz]
+  // for atmega328 fixed to 32kHz
+  // esp32/stm32/teensy configurable
+  driver.pwm_frequency = 32000;
+  // power supply voltage [V]
+  driver.voltage_power_supply = 5;
+  // Max DC voltage allowed - default voltage_power_supply
+  driver.voltage_limit = 5;
+  // daad_zone [0,1] - default 0.02f - 2%
+  driver.dead_zone = 0.05f;
+
+  // driver init
+  driver.init();
+
+  // enable driver
+  driver.enable();
+
+  _delay(1000);
+}
+
+void loop() {
+    driver.setPwm(5,0,0);
+    _delay(1000);
+    
+    driver.setPwm(0,5,0);
+    _delay(1000);
+}

docs/README.md

@@ -0,0 +1,76 @@
+// Open loop motor control example
+#include <SimpleFOC.h>
+
+
+// BLDC motor & driver instance
+// BLDCMotor motor = BLDCMotor(pole pair number);
+BLDCMotor motor = BLDCMotor(7);
+// BLDCDriver3PWM driver = BLDCDriver3PWM(pwmA, pwmB, pwmC, Enable(optional));
+BLDCDriver6PWM driver = BLDCDriver6PWM(5, 6, 9,10, 3, 11);
+
+// Stepper motor & driver instance
+//StepperMotor motor = StepperMotor(50);
+//StepperDriver4PWM driver = StepperDriver4PWM(9, 5, 10, 6,  8);
+
+
+//target variable
+float target_velocity = 6;
+
+// // instantiate the commander
+Commander command = Commander(Serial);
+// void doTarget(char* cmd) { command.scalar(&target_velocity, cmd); }
+// void doLimit(char* cmd) { command.scalar(&motor.voltage_limit, cmd); }
+
+void setup() {
+
+  // driver config
+  // power supply voltage [V]
+  driver.voltage_power_supply = 5;
+  // limit the maximal dc voltage the driver can set
+  // as a protection measure for the low-resistance motors
+  // this value is fixed on startup
+  driver.voltage_limit = 5;
+  // pwm frequency to be used [Hz]
+  // for atmega328 fixed to 32kHz
+  // esp32/stm32/teensy configurable
+  driver.pwm_frequency = 32000;
+  
+
+  driver.init();
+  // link the motor and the driver
+  motor.linkDriver(&driver);
+
+  // limiting motor movements
+  // limit the voltage to be set to the motor
+  // start very low for high resistance motors
+  // current = voltage / resistance, so try to be well under 1Amp
+  motor.voltage_limit = 3;   // [V]
+ 
+  // open loop control config
+  motor.controller = MotionControlType::velocity_openloop;
+
+  // init motor hardware
+  motor.init();
+
+  // add target command T
+  // command.add('T', doTarget, "target velocity");
+  // command.add('L', doLimit, "voltage limit");
+
+  Serial.begin(115200);
+  Serial.println("Motor ready!");
+  Serial.println("Set target velocity [rad/s]");
+  _delay(1000);
+
+}
+
+void loop() {
+
+  // open loop velocity movement
+  // using motor.voltage_limit and motor.velocity_limit
+  motor.move(target_velocity);
+
+  // user communication
+  command.run();
+
+  
+}

docs/arduino_examples/6PWM_utils/6PWM_utils.ino

@@ -0,0 +1,35 @@
+// BLDC driver standalone example
+#include <SimpleFOC.h>
+
+// BLDC driver instance
+BLDCDriver6PWM driver = BLDCDriver6PWM(5, 6, 9,10, 3, 11);
+
+void setup() {
+
+  // pwm frequency to be used [Hz]
+  // for atmega328 fixed to 32kHz
+  // esp32/stm32/teensy configurable
+  driver.pwm_frequency = 32000;
+  // power supply voltage [V]
+  driver.voltage_power_supply = 5;
+  // Max DC voltage allowed - default voltage_power_supply
+  driver.voltage_limit = 5;
+  // daad_zone [0,1] - default 0.02f - 2%
+  driver.dead_zone = 0.05f;
+
+  // driver init
+  driver.init();
+
+  // enable driver
+  driver.enable();
+
+  _delay(1000);
+}
+
+void loop() {
+    driver.setPwm(5,0,0);
+    _delay(1000);
+    
+    driver.setPwm(0,5,0);
+    _delay(1000);
+}

docs/arduino_examples/BLDC/BLDC.ino

@@ -0,0 +1,62 @@
+## Hardware Assembly
+
+Users should already have followed the instructions from the [component assembly](../../component_assembly) and [example setups](../../hardware_assembly) sections to setup their hardware for this example.
+
+<figure markdown>
+[![](../img/hookup_guide/example-BLDC_motor.jpg){ width="200" }](../img/hookup_guide/example-BLDC_motor.jpg "Click to enlarge")
+<figcaption markdown>
+A graphical representation of the connections between the [RedBoard Plus](https://www.sparkfun.com/products/18158) and a [breadboard](https://www.sparkfun.com/products/12002) with the [TMC6300 motor driver](https://www.sparkfun.com/products/21867) attached.
+</figcaption>
+</figure>
+
+
+### RedBoard Plus to TMC6300
+
+Connect the following pins from the RedBoard Plus to the TMC6300.
+
+--8<-- "./docs/hardware_assembly.md:12:26"
+
+### Connecting the Gimbal Motor
+
+--8<-- "./docs/hardware_assembly.md:45:52"
+
+### Powering the TMC6300
+
+If users are unable to find a suitable power source, we have found that the 5V power output from the RedBoard Plus is sufficient to drive the gimbal motor, under a no load condition at low speeds.
+
+--8<-- "./docs/hardware_assembly.md:83:97"
+
+
+## Example Code
+
+After installing and setting up the Arduino IDE and the Simple FOC Arduino library, users will need to upload the following example code to the RedBoard Plus. This code can be copied or downloaded below:
+
+<center>
+[:octicons-download-16:{ .heart } Download `BLDC.ino` Example Code](../BLDC/BLDC.ino){ .md-button .md-button--primary }
+</center>
+
+!!! code "Example Code"
+    ``` c++ title="BLDC.ino"
+        --8<-- "./docs/arduino_examples/BLDC/BLDC.ino"
+    ```
+
+### Running the Motor
+
+Be default, the motor should spin automatically. However, if users wish to control the speed of the motor, they can uncomment lines **21-22** and **56-57** of code and reprogram the RedBoard Plus.
+
+??? code "Code Changes Highlighted"
+    Uncomment the following lines of code (**21-22** and **56-57**):
+
+    ``` c++ hl_lines="21-22 56-57" title="BLDC.ino"
+        --8<-- "./docs/arduino_examples/BLDC/BLDC.ino"
+    ```
+
+In order to drive the motor, users will need to access the [serial monitor](https://learn.sparkfun.com/tutorials/8) and provide the [commands](https://docs.simplefoc.com/commands_source) necessary to drive the motor. A full list of the available commands can be found in the [Simple FOC Arduino library documentation](https://docs.simplefoc.com/commands_source). However, only the `T` and `L` commands are enabled in the example code.
+
+* Sending a `T` command will set the target motor velocity in rads/s
+    * Example - Entering `T6` into the serial monitor, will set the target motor velocity to 6 radians/s.
+* Sending a `L` command will set the voltage limit of the motor driver and in turn, the current limit *(voltage_limit / motor_resistance)*
+    * Example - Entering `L5` into the serial monitor, will set the voltage limit to 5V and the current limit to .5A *(5V/10&ohm;)*.
+
+!!! tip "Baud Rate"
+    THe serial monitor baud rate should be configured to 115200bps.

docs/arduino_examples/DC/DC.ino

@@ -0,0 +1,58 @@
+## Hardware Assembly
+
+Users should already have followed the instructions from the [component assembly](../../component_assembly) and [example setups](../../hardware_assembly) sections to setup their hardware for this example.
+
+<figure markdown>
+[![](../img/hookup_guide/example-DC_motor.jpg){ width="200" }](../img/hookup_guide/example-DC_motor.jpg "Click to enlarge")
+<figcaption markdown>
+A graphical representation of the connections between the [RedBoard Plus](https://www.sparkfun.com/products/18158) and a [breadboard](https://www.sparkfun.com/products/12002) with the [TMC6300 motor driver](https://www.sparkfun.com/products/21867) attached.
+</figcaption>
+</figure>
+
+
+### RedBoard Plus to TMC6300
+
+Connect the following pins from the RedBoard Plus to the TMC6300.
+
+--8<-- "./docs/hardware_assembly.md:12:26"
+
+### Connecting the DC Motor
+
+--8<-- "./docs/hardware_assembly.md:71:71"
+
+### Powering the TMC6300
+
+If users are unable to find a suitable power source, we have found that the 5V power output from the RedBoard Plus is sufficient to drive the gimbal motor, under a no load condition at low speeds.
+
+--8<-- "./docs/hardware_assembly.md:83:97"
+
+
+## Example Code
+
+After installing and setting up the Arduino IDE and the Simple FOC Arduino library, users will need to upload the following example code to the RedBoard Plus. This code can be copied or downloaded below:
+
+<center>
+[:octicons-download-16:{ .heart } Download `DC.ino` Example Code](../DC/DC.ino){ .md-button .md-button--primary }
+</center>
+
+!!! code "Example Code"
+    ``` c++ title="DC.ino"
+        --8<-- "./docs/arduino_examples/DC/DC.ino"
+    ```
+
+### Running the Motor
+
+Be default, the motor should spin automatically. However, if users wish to control the motor, they can modify lines **30** and **33** of code and reprogram the RedBoard Plus. These lines control the high and low-side MOSFETS of the H-bridge directly through pins `5`, `6`, `9`, and `10`.
+
+??? code "Code Changes Highlighted"
+    MOdify the following lines of code (**30** and **33**):
+
+    ``` c++ hl_lines="30 33" title="DC.ino"
+        --8<-- "./docs/arduino_examples/DC/DC.ino"
+    ```
+
+* The PWM voltage value `driver.setPwm(voltage_value,0,0)` affects the speed of the motor.
+* The position of this value inr elation to the PWM drive channel `driver.setPwm(channel_v,channel_w,0)` affects the direction.
+
+??? tip
+    Users may also be interested in the [SimpleDC Motor library](https://docs.simplefoc.com/dc_motors_library) to drive DC motors with the Simple FOC Arduino library.