+
+
+
+
+
+## Features
+- **Plug & play**: In combination with Arduino SimpleFOClibrary
+- **DRV8313 based** - [datasheet](https://www.ti.com/lit/ds/symlink/drv8313.pdf?ts=1650461862269&ref_url=https%253A%252F%252Fwww.google.com%252F)
+ - Power supply: 8-24V
+ - Max current: 2.5A per phase
+ - Onboard 3.3V LDO
+- **Small size**: 26x20 mm
+- **Fully open-source**:
+ - [EasyEDA](https://easyeda.com/the.skuric/simplefocmini)
+ - [GitHub](https://github.com/simplefoc/SimpleFOCMini)
+- **Low-cost**:
+ - JLCPCB production cost ~3-5β¬
+ - Will be available in the [shop](https://www.simplefoc.com/shop) soon: 7-10β¬
+
+ Read more about this board at [link](https://github.com/simplefoc/SimpleFOCMini)
+
## Arduino SimpleFOC PowerShield v0.2 β οΈ( under developement)
A powerful arduino shield for running BLDC motors using the FOC algorithm. This board is based on the [BTN8982](https://www.infineon.com/dgdl/Infineon-BTN8982TA-DS-v01_00-EN.pdf?fileId=db3a30433fa9412f013fbe32289b7c17) half bridges and can support currents up to 30 Amps continuos and 50Amps peak. Making it a board that can run virtually any BLDC motor.
@@ -78,29 +104,3 @@ This does not mean that the board itself is not functional or that it will not w
- schematics
Read more about this board at [link](https://github.com/simplefoc/Arduino-SimpleFOC-PowerShield)
-
-## π’**NEW**: SimpleFOCMini v1.0
-
-Small package, low-cost BLDC driver board fully compatible with the SimpleFOClibrary
-
-
-
-
-
-
-
-## Features
-- **Plug & play**: In combination with Arduino SimpleFOClibrary
-- **DRV8313 based** - [datasheet](https://www.ti.com/lit/ds/symlink/drv8313.pdf?ts=1650461862269&ref_url=https%253A%252F%252Fwww.google.com%252F)
- - Power supply: 8-24V
- - Max current: 2.5A per phase
- - Onboard 3.3V LDO
-- **Small size**: 26x20 mm
-- **Fully open-source**:
- - [EasyEDA](https://easyeda.com/the.skuric/simplefocmini)
- - [GitHub](https://github.com/simplefoc/SimpleFOCMini)
-- **Low-cost**:
- - JLCPCB production cost ~3-5β¬
- - Will be available in the [shop](https://www.simplefoc.com/shop) soon: 7-10β¬
-
- Read more about this board at [link](https://github.com/simplefoc/SimpleFOCMini)
\ No newline at end of file
diff --git a/docs/boards/simplefoc_mini/getting_started/code.md b/docs/boards/simplefoc_mini/getting_started/code.md
new file mode 100644
index 0000000..717310a
--- /dev/null
+++ b/docs/boards/simplefoc_mini/getting_started/code.md
@@ -0,0 +1,102 @@
+---
+layout: default
+title: Writing the code
+parent: Starting with Mini
+description: "Writing the Arduino program for your SimpleFOCMini."
+nav_order: 2
+permalink: /mini_code
+grand_parent: SimpleFOCMini
+grand_grand_parent: SimpleFOC Boards
+---
+
+# Writing the code
+Once you have all the [hardware connected](mini_connect_hardware):
+- Microcontroller
+- BLDC motor
+- Position sensor
+- Power supply
+
+we can start the most exciting part, coding!
+
+SimpleFOCMini is fully supported by Arduino SimpleFOClibrary, therefore please make sure you have the newest version of the SimpleFOClibrary installed. If you still did not get your owm version of the library please follow the [installation instructions](installation).
+
+Suggested approach when starting coding for the Arduino SimpleFOCMini is:
+
+- [Test the sensor](#step-1-testing-the-sensor)
+- [Test the motor](#step-2-testing-the-motor)
+- [Voltage motion control](#step-3-voltage-motion-control)
+- [More complex control strategies](#step-4-more-complex-control-strategies) - position and velocity
+
+You can also follow our [Getting started](example_from_scratch) guide!
+
+## Step 1. Testing the sensor
+First make sure your sensor works properly. Run one of the library examples specific to your sensors. You can find the library examples in
+```sh
+utils >
+ sensor_test >
+ encoder >
+ - encoder_example
+ - encoder_software_interrupts_example
+ magnetic_sensors >
+ - magnetic_sensor_i2c_example
+ - magnetic_sensor_spi_example
+ - magnetic_sensor_analog_example
+ hall_sensors >
+ - hall_sensor_example
+ - hall_sensor_software_interrupts_example
+```
+Once you have your sensor reading the good values you can continue the testing the combination of the motor and the sensor.
+
++ +## Step 2. Testing the motor +To test the BLDC motor before running FOC algorithm we suggest to run the open loop examples! +```sh +motion_control > + open_loop_motor_control > + - open_loop_position_example + - open_loop_velocity_example +``` +Update the example pinout
+When testing the sensor make sure to update the pinout.
+ +If you are not sure what is the number of pole pairs your motor has, please check the example code: +```sh +utils > + find_pole_pair_number > + - encoder + - magnetic_sensor +``` +This code will estimate the pole pairs number that your motor has. Please run this code several times to get a good estimation. The code will, generally show a good reading 7/10 times. + + +## Step 3. Voltage motion control +Once you have your sensor working, and you have the right number of pole pairs of your motor you can start using FOC algorithm. The best practice is to start with an example of the Voltage control: +```sh +motion_control > + torque_voltage_control > + - encoder + - magnetic_sensor + - hall_sensors +``` + +## Step 4. More complex control strategies +Now when you have your torque control using voltage ready you can continue to the position and velocity control algorithms. They will take a bit more time to tune but they will give you a chance to have great results. You can find the library examples for motion control loops in by navigating the examples: + +```sh +motion_control > + position_motion_control > + - encoder + - magnetic_sensor + - hall_sensors + torque_voltage_control > + - encoder + - magnetic_sensor + - hall_sensors + velocity_motion_control > + - encoder + - magnetic_sensor + - hall_sensors +``` +For more information about the possible SimpleFOCMini projects visit [example projects](examples) diff --git a/docs/boards/simplefoc_mini/getting_started/connections.md b/docs/boards/simplefoc_mini/getting_started/connections.md new file mode 100644 index 0000000..48446d7 --- /dev/null +++ b/docs/boards/simplefoc_mini/getting_started/connections.md @@ -0,0 +1,136 @@ +--- +layout: default +title: Connecting the hardware +parent: Starting with Mini +description: "Connecting SimpleFOCMini with your hardware." +nav_order: 1 +permalink: /mini_connect_hardware +grand_parent: SimpleFOCMini +grand_grand_parent: SimpleFOC Boards +--- + +# Connecting the hardware + +Update the example pinout
+When testing the motor make sure to update the pinout that you have chosen in the hardware configuration.
+
+
+
+
+
+
+ +Pin `nFT` (fault) is an active LOW output of the SimpleFOCMini which can be read to verify if the DRV8313 driver is working properly. If this pin is in LOW it means the DRV8313 is its fault state and it cannot drive the motor. Then the pin `nRT` (reset), which is also active LOW, can be used to reset the DRV8313 driver to reinitialise its internal state and exit the fault state, this cannot be done by simply toggling the enable pin. Finally the pin `nSP` (sleep) is an active LOW pin that puts the DRV8313 in the low-power sleep mode, consuming the current of under 1uA. + + + + + +## BLDC motor +- Motor phases `a`, `b` and `c` are connected directly the motor terminal connector `M1`,`M2` and `M3` + +BEWARE: 3.3V LDO Power limitations
+DRV8313 comes with the 3.3V voltage regulator and it is connected to the SimpleFOCMini's 3.3V pin. However it has a limitation of 10mA, which is in general not enough to power a microcontroller. But it might be enough to power a LED light or some position sensors. +
+ +## Power supply +- Power supply cables are connected directly to the terminal pins `+` and `-` +- Required power supply voltage is from 8V to 24V. + + +## Examples of connection schematics + +SimpleFOCMini can be connected to any microcontroller (MCU) pin combination that can ensure that the mini's `GND` pin is connected to the MCU's `GND` pin, MCU's 3 pwm capable pins are connected to the `IN1`,`IN2` and `IN3` pins, and one MCU's digital pin is connected to the `EN` pin. + + +An example connection of the SimpleFOCMini and Nucleo board is shown on the image below. + +BEWARE: Power limitations
+SimpleFOCMini is designed for gimbal motors with internal resistance higher than R>10Ohm. The absolute maximal current of this board is 5A. Please make sure when using this board in your projects that the BLDC motor used does comply with these limits.
+If you still want to use this driver with the BLDC motors with very low resistance R < 1Ohm make sure to limit the voltage set to the board.
+For a bit more information about the choice of motors visit BLDC motor docs +
+
+SimpleFOCMini can be directly plugged into the Arduino headers of teh Nucleo board from the pin `10` to the `GND` pin and in that way reduce the amount of wires necessary. For more information on this example connection see [this library example](mini_example_nucleo).
+
+--- | --- | --- | ---| --- | ---
+Mini Pin | EN | IN3 | IN2 | IN1 | GND
+Nucleo Pin | 10 | 11 | 12 | 13 | GND
+
+```cpp
+BLDCDriver3PWM driver = BLDCDriver3PWM(13, 12, 11, 10);
+```
+
+An example connection of the SimpleFOCMini and Arduino UNO is shown on the image below.
+
+
+SimpleFOCMini can be directly plugged into the Arduino headers of the UNO board from the pin `8` to the `12` pin (pin 12 can act as a GND pin) and in that way reduce the amount of wires necessary. For more information on this example connection see [this library example](mini_example).
+
+--- | --- | --- | ---| --- | ---
+Mini Pin | EN | IN3 | IN2 | IN1 | GND
+UNO Pin | 8 | 9 | 10 | 11 | 12
+
+```cpp
+BLDCDriver3PWM driver = BLDCDriver3PWM(11, 10, 9, 8);
+```
+
+Another example of connecting the Arduino UNO with SimpleFOCMini is shown below
+
+
+--- | --- | --- | ---| --- | ---
+Mini Pin | EN | IN3 | IN2 | IN1 | GND
+UNO Pin | 4 | 5 | 6 | 9 | GND
+
+```cpp
+BLDCDriver3PWM driver = BLDCDriver3PWM(9, 6, 5, 4);
+```
+
+An example connection of the SimpleFOCMini and stm32 Bluepill is shown on the image below.
+
+
+
+--- | --- | --- | ---| --- | ---
+Mini Pin | EN | IN3 | IN2 | IN1 | GND
+Bluepill Pin | PB15 | PA8 | PA9 | PA10 | GND
+
+```cpp
+BLDCDriver3PWM driver = BLDCDriver3PWM(PA10, PA9, PA8, PB15);
+```
\ No newline at end of file
diff --git a/docs/boards/simplefoc_mini/getting_started/index.md b/docs/boards/simplefoc_mini/getting_started/index.md
new file mode 100644
index 0000000..6a3ee18
--- /dev/null
+++ b/docs/boards/simplefoc_mini/getting_started/index.md
@@ -0,0 +1,28 @@
+---
+layout: default
+title: Starting with Mini
+description: "Getting started with Arduino SimpleFOCMini"
+parent: SimpleFOCMini
+grand_parent: SimpleFOC Boards
+nav_order: 1
+permalink: /mini_getting_started
+has_children: true
+has_toc: false
+---
+# Getting Started with SimpleFOCMini
+
+
+
+## Step 1: [Connecting the hardware](mini_connect_hardware)
+
+
+
+Connecting the SimpleFOCMini to the microcontroller, BLDC motor and power-supply is straight forward.
+
+[Read more](mini_connect_hardware)
+
+## Step 2: [Writing the code](mini_code)
+
+Once you have all the hardware [ready to be connected](mini_connect_hardware), we can start the most exciting part, coding!
+
+[Read more](mini_code)
\ No newline at end of file
diff --git a/docs/boards/simplefoc_mini/index.md b/docs/boards/simplefoc_mini/index.md
new file mode 100644
index 0000000..9cf81c5
--- /dev/null
+++ b/docs/boards/simplefoc_mini/index.md
@@ -0,0 +1,98 @@
+---
+layout: default
+title: SimpleFOCMini
+parent: SimpleFOC Boards
+description: "Arduino SimpleFOCShield board showcase."
+nav_order: 2
+permalink: /simplefocmini
+has_children: true
+has_toc: false
+---
+
+
+# SimpleFOCMini v1.0
+
+SimpleFOCMini is a small-package, low-cost, modular and user-friendly driver for running gimbal BLDC motors with FOC algorithm. As for the SimpleFOCShields, the main motivation of this board is to make using low-power BLDC motors in hobby applications more accessible.
+The main goals of this board however are:
+
+- Produce a small package BLDC driver that still has all the features of the SimpleFOCShield v1
+- Make it in away to be a minimal working example for users that are interested to build their own boards based on the DRV8313 chip.
+- Make it as cheap as possible.
+- Use only long-term (as of mid 2022) available components.
+- Finally, the goal of this board is to provide a modular and simple setup for controlling gimbal motors (up to 3Amps) using FOC control and enable fast prototyping and full exploitation of their capabilities.
+
+This board in combination with the SimpleFOClibrary will give you a simple and intuitive way to control the BLDC motors' current, torque, velocity and position. And this board can be used as a drop in replacement for the SimpleFOCShield v1.
+
+
+
+
+
+## Features
+- **Plug & play**: In combination with Arduino SimpleFOClibrary
+- **DRV8313 based** - [datasheet](https://www.ti.com/lit/ds/symlink/drv8313.pdf?ts=1650461862269&ref_url=https%253A%252F%252Fwww.google.com%252F)
+ - Power supply: 8-24V
+ - Max current: 2.5A per phase
+ - Onboard 3.3V LDO
+- **Small size**: 26x20 mm
+- **Fully open-source**:
+ - [EasyEDA](https://easyeda.com/the.skuric/simplefocmini)
+ - [GitHub](https://github.com/simplefoc/SimpleFOCMini)
+- **Low-cost**:
+ - JLCPCB production cost ~3-5β¬
+ - Will be available in the [shop](https://www.simplefoc.com/shop) soon: 7-10β¬
+
+
+
+++ +BEWARE
+This BLDC driver board is primarily designed for gimbal motors with the internal resistance of R >10 Ξ©. Please make sure that your motor fits in this category before deciding to use the SimpleFOCMini. +
+
+### Connection schematic
+An electrical connection example of a BLDC motor with an encoder as position sensor.
+
+ +## Project example : Steer by wire - bidirectional haptic control examples + + +This video demonstrates SimpleFOCShield support for stacking with Arudino UNO and STM32 Nucleo-64 board. As well as support for different sensors magnetic and encoders with relatively large precision span. + +The control algorithms implemented in this project are : +- **Steer by wire** (force feedback): two motors with virtually coupled positions +- **Interactive gauge** (haptic velocity control): two motors with virtually coupled position and velocity + + +For full documentation of the projects setup and the code please visit the [project docs](haptics_examples). + +π’ +This project can be entirely done by using the SimpleFOCMini board.
+
+ +## Getting started + +You already have your own SimpleFOCMini?π’ +This project can be entirely done by using the SimpleFOCMini board.
+
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
+ SimpleFOC: A Field Oriented Control (FOC) Library for Controlling Brushless Direct Current (BLDC) and Stepper Motors.
+ A. Skuric, HS. Bank, R. Unger, O. Williams, D. GonzΓ‘lez-Reyes
+Journal of Open Source Software, 7(74), 4232, https://doi.org/10.21105/joss.04232
+
+
+@article{simplefoc2022,
+ doi = {10.21105/joss.04232},
+ url = {https://doi.org/10.21105/joss.04232},
+ year = {2022},
+ publisher = {The Open Journal},
+ volume = {7},
+ number = {74},
+ pages = {4232},
+ author = {Antun Skuric and Hasan Sinan Bank and Richard Unger and Owen Williams and David GonzΓ‘lez-Reyes},
+ title = {SimpleFOC: A Field Oriented Control (FOC) Library for Controlling Brushless Direct Current (BLDC) and Stepper Motors},
+ journal = {Journal of Open Source Software}
+}
+
+
+
\ No newline at end of file
diff --git a/docs/simplefoc_library/code/current_sense/index.md b/docs/simplefoc_library/code/current_sense/index.md
index 28c6b24..9ef9df6 100644
--- a/docs/simplefoc_library/code/current_sense/index.md
+++ b/docs/simplefoc_library/code/current_sense/index.md
@@ -42,23 +42,25 @@ The current sense code will be written in a way to support as many different dri
Also make sure to follow our [community forum](https://community.simplefoc.com), a lot of discussions is being held about current sensing and its applications!
## Current sensing support per MCU architecture
-
+
MCU | In-line | Low-side | High-side
--- | --- |--- |---
Arduino (8-bit) | βοΈ | β | β
Arduino DUE | βοΈ | β | β
-STM32 (in general) | βοΈ | β | β
-STM32F1 family | βοΈ | βοΈ (one motor) | β
-STM32F4 family | βοΈ | βοΈ (one motor) | β
-STM32G4 family | βοΈ | βοΈ (one motor) | β
-STM32 B-G431B-ESC1 | βοΈ | βοΈ | β
-ESP32 | βοΈ | βοΈ | β
-ESP8266 | β | β | β
-SAMD21 | βοΈ | βοΈ (one motor) | β
-SAMD51 | βοΈ | β | β
-Teensy | βοΈ | β | β
+stm32 (in general) | βοΈ | β | β
+stm32f1 family | βοΈ | βοΈ (one motor) | β
+stm32f4 family | βοΈ | βοΈ (one motor) | β
+stm32g4 family | βοΈ | βοΈ (one motor) | β
+stm32 B_G431B_ESC1 | β | βοΈ (one motor) | β
+esp32/esp32s3 | βοΈ | βοΈ | β
+esp32s2/esp32c3 | βοΈ | β | β
+esp8266 | β | β | β
+samd21 | βοΈ | βοΈ (one motor) | β
+samd51 | βοΈ | β | β
+teensy | βοΈ | β | β
Raspberry Pi Pico | βοΈ | β | β
Portenta H7 | βοΈ | β | β
+nRF52 | βοΈ | β | β
## Digging deeper
diff --git a/docs/simplefoc_library/code/current_sense/low_side.md b/docs/simplefoc_library/code/current_sense/low_side.md
index e1313ac..e1f0129 100644
--- a/docs/simplefoc_library/code/current_sense/low_side.md
+++ b/docs/simplefoc_library/code/current_sense/low_side.md
@@ -187,7 +187,7 @@ It is very important that the the current sensing `init` function is called afte
So the suggested code structure would be:
```cpp
-void loop(){
+void setup(){
....
// driver init
driver.init();
diff --git a/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_3pwm.md b/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_3pwm.md
index 5296731..08338f8 100644
--- a/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_3pwm.md
+++ b/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_3pwm.md
@@ -119,6 +119,22 @@ Once when all the necessary configuration parameters are set the driver function
driver.init();
```
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init()) Serial.println("success!");
+else{
+ Serial.println("failed!");
+ return;
+}
+```
+
## Step 3. Using `BLDCDriver3PWM` in real-time
BLDC driver class was developed to be used with the SimpleFOClibrary and to provide the abstraction layer for FOC algorithm implemented in the `BLDCMotor` class. But the `BLDCDriver3PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the bldc driver.
diff --git a/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_6pwm.md b/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_6pwm.md
index e7af5a4..01e732c 100644
--- a/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_6pwm.md
+++ b/docs/simplefoc_library/code/drivers/bldc_driver/bldc_driver_6pwm.md
@@ -186,6 +186,22 @@ Once when all the necessary configuration parameters are set the driver function
driver.init();
```
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init()) Serial.println("success!");
+else{
+ Serial.println("failed!");
+ return;
+}
+```
+
## Step 3. Using `BLDCDriver6PWM` in real-time
BLDC driver class was developed to be used with the SimpleFOClibrary and to provide the abstraction layer for FOC algorithm implemented in the `BLDCMotor` class. But the `BLDCDriver3PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the BLDC driver.
diff --git a/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_2pwm.md b/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_2pwm.md
index 089e108..84698f8 100644
--- a/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_2pwm.md
+++ b/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_2pwm.md
@@ -101,6 +101,22 @@ Once when all the necessary configuration parameters are set the driver function
driver.init();
```
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init()) Serial.println("success!");
+else{
+ Serial.println("failed!");
+ return;
+}
+```
+
## Step 3. Using encoder in real-time
BLDC driver class was developed to be used with the SimpleFOClibrary and to provide the abstraction layer for FOC algorithm implemented in the `StepperMotor` class. But the `StepperDriver4PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the BLDC driver.
diff --git a/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_4pwm.md b/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_4pwm.md
index 40bc5cd..a20ecea 100644
--- a/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_4pwm.md
+++ b/docs/simplefoc_library/code/drivers/stepper_driver/stepper_driver_4pwm.md
@@ -77,6 +77,22 @@ Once when all the necessary configuration parameters are set the driver function
driver.init();
```
+This function is responsible for:
+- determining and configuring the hardware timer for PWM generation
+- verifying that all provided pins can be used to generate PWM
+- configuring the PWM channels
+
+If for some reason the driver configuration fails this function will return `0` if everything went well the function will return `1`. So we suggest you to check if the init function was executed successfully before continuing
+```cpp
+Serial.print("Driver init ");
+// init driver
+if (driver.init()) Serial.println("success!");
+else{
+ Serial.println("failed!");
+ return;
+}
+```
+
## Step 3. Using encoder in real-time
BLDC driver class was developed to be used with the SimpleFOClibrary and to provide the abstraction layer for FOC algorithm implemented in the `StepperMotor` class. But the `StepperDriver4PWM` class can used as a standalone class as well and once can choose to implement any other type of control algorithm using the BLDC driver.
diff --git a/docs/simplefoc_library/code/drivers_library.md b/docs/simplefoc_library/code/drivers_library.md
index e09ed25..3d04d1c 100644
--- a/docs/simplefoc_library/code/drivers_library.md
+++ b/docs/simplefoc_library/code/drivers_library.md
@@ -49,7 +49,7 @@ It is steadily growing, but at the moment we have:
## How can I use it?
-```c++
+```cpp
#include "SimpleFOCDrivers.h"
```
@@ -57,7 +57,7 @@ It is in the arduino library manager, called "Simple FOC Drivers". Install as no
To use some code from the library, include the specific driver module you want. For example:
-```c++
+```cpp
#include "encoders/as5048a/MagneticSensorAS5048A.h"
```
diff --git a/docs/simplefoc_library/code/motors/bldc_motors.md b/docs/simplefoc_library/code/motors/bldc_motors.md
index 8baac31..c55bbec 100644
--- a/docs/simplefoc_library/code/motors/bldc_motors.md
+++ b/docs/simplefoc_library/code/motors/bldc_motors.md
@@ -237,12 +237,22 @@ motor.initFOC();
This function does several things: +- Checks if driver (and current sense if available) are well initialised - Checks/modifies position sensor direction in respect to the motor's direction - Searches for encoder index if necessary - Finds the motor electrical offset in respect to the position sensor - Checks/modifies current sense pinout and gains signs if one available to make sure it aligned with the driver -This function is a final check function and it will disable your motor and display you a message what is wrong. (when using the [monitoring](monitoring) ). If everything is well configured, after the call of this function FOC is ready and our setup is done! +If for some reason the `initFOC` fails this function will return `0` and it will disable your motor and display you a message what is wrong (when using the [monitoring](monitoring) ). If everything is well configured, the call of this function will return `1` and the our setup is done, FOC is ready to be used! So we suggest you to check if the init function was executed successfully before continuing: + +```cpp +// init current sense +if (motor.initFOC()) Serial.println("FOC init success!"); +else{ + Serial.println("FOC init failed!"); + return; +} +``` The alignment procedure will have to move your motor several times and might not be desirable behavior, therefore for most of the position sensors (except encodes) and current senses, this alignment procedure can be skipped by following the steps 6.1 an 6.2. diff --git a/docs/simplefoc_library/code/motors/stepper_motors.md b/docs/simplefoc_library/code/motors/stepper_motors.md index 6daf86a..8222726 100644 --- a/docs/simplefoc_library/code/motors/stepper_motors.md +++ b/docs/simplefoc_library/code/motors/stepper_motors.md @@ -203,12 +203,22 @@ motor.initFOC();Can be skipped for openloop control!
If no sensor is attached this function will not really do anything, but you can still call it if necessary or more convenient.
This function does several things: +- Checks if driver (and current sense if available) are well initialised - Checks/modifies position sensor direction in respect to the motor's direction - Searches for encoder index if necessary - Finds the motor electrical offset in respect to the position sensor +- Checks/modifies current sense pinout and gains signs if one available to make sure it aligned with the driver -This function is a final check function and it will disable your motor and display you a message what is wrong. (when using the [monitoring](monitoring) ). If everything is well configured, after the call of this function FOC is ready and our setup is done! +If for some reason the `initFOC` fails this function will return `0` and it will disable your motor and display you a message what is wrong (when using the [monitoring](monitoring) ). If everything is well configured, the call of this function will return `1` and the our setup is done, FOC is ready to be used! So we suggest you to check if the init function was executed successfully before continuing: +```cpp +// init current sense +if (motor.initFOC()) Serial.println("FOC init success!"); +else{ + Serial.println("FOC init failed!"); + return; +} +``` The alignment procedure will have to move your motor several times and might not be desirable behavior, therefore for most of the position sensors (except encodes) and current senses, this alignment procedure can be skipped by following the steps 5.1. ### Step 5.1 Skip alignment - position sensor diff --git a/docs/simplefoc_library/code/sensors/encoder.md b/docs/simplefoc_library/code/sensors/encoder.md index 1ea956d..f14b2df 100644 --- a/docs/simplefoc_library/code/sensors/encoder.md +++ b/docs/simplefoc_library/code/sensors/encoder.md @@ -254,6 +254,16 @@ class Encoder{ } ``` +Can be skipped for openloop control!
If no sensor is attached this function will not really do anything, but you can still call it if necessary or more convenient.
++ + Here is a quick example: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +encoder.min_elapsed_time = 0.0001; // 100us by default +``` +
++ Here is a quick example: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
+### Step 2.1 Velocity outlier removal + +From the release v2.2.3 `HallSensor` class implements the outlier removal for its velocity calculations. It is based on a simple principle where all the calculated velocities higher than a certain maximal expected velocity are considered to be an outlier. To modify the maximal expected motor velocity, you can modify the variable `velocity_max`. This variable is set to 1000rad/s by default which is a good starting point for most applications. Except if you are using very high performance motors, then 1000 rad/s (~10,000 rpm) could still be reachable by the motor in which case please increase this value to a number outside the motor's reach. + +```cpp +// maximal expected velocity +sensor.velocity_max = 1000; // 1000rad/s by default ~10,000 rpm +``` ## Step 3. Interrupt setup There are two ways you can run hall sensors with Simple FOC library. - Using [hardware external interrupt](#hardware-external-interrupt) @@ -181,6 +189,15 @@ class HallSensor{ } ``` +Arduino Pullup 20kΞ©
Be careful when using internal pullups, Arduino has relatively high valued pullups around 20kΞ©, which means that you might have some problems for higher velocities (for shorted impulse durations). Recommended pull-up values are in between 1kΞ© and 5kΞ©.
++ Here is a quick example using only hardware interrupts: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
++ + Here is a quick example for AS5600 magnetic sensor using it's analog output: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
++ + + Here is a quick example for AS5600 magnetic sensor with I2C communication: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
++ + + +Calling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
++ + + +Calling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
++ + + Here is a quick example for AS5048A magnetic sensor using its PWM output: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
++ + + Here is a quick example for the AS5047U magnetic sensor with SPI communication: ```cpp #includeCalling `getVelocity` multiple times
+When calling `getVelocity` it will only calculate the velocity if the elapsed time from the previous call is longer than the time specified in teh variable `min_elapsed_time` (default 100us). If the elapsed time from the last call is shorter than `min_elapsed_time` the function will return previously calculated value. Variable `min_elapsed_time` can be changed easily if necessary: + +```cpp +sensor.min_elapsed_time = 0.0001; // 100us by default +``` +
| 
| 
| 
| 
+Download the STL file as well as STEP and solidworks project of the 3d printed stand for the IPower GM4108H-120T motor with the mount for the CUI amt103 encoder, used in the images and the Youtube video, [here](extras/gm4108_encoder_mount.zip).
+
## Connecting everything together
Here is a picture of the setup used in this project. Check the Arduino code to see the pin numbers that are used.
diff --git a/docs/simplefoc_library/examples/index.md b/docs/simplefoc_library/examples/index.md
index ffd931b..e660f3e 100644
--- a/docs/simplefoc_library/examples/index.md
+++ b/docs/simplefoc_library/examples/index.md
@@ -57,4 +57,16 @@ parent: Arduino SimpleFOClibrary
+
+
+
+
+
+
+
| | |
@@ -241,5 +241,7 @@ void loop() {
// function calculating the outer position loop and setting the target position
motor.move(target_angle);
+ // user communication
+ command.run();
}
```
diff --git a/docs/simplefoc_library/examples/position_control_example_mini.md b/docs/simplefoc_library/examples/position_control_example_mini.md
new file mode 100644
index 0000000..2e2695f
--- /dev/null
+++ b/docs/simplefoc_library/examples/position_control_example_mini.md
@@ -0,0 +1,261 @@
+---
+layout: default
+title: SimpleFOCMini & UNO
+parent: Example projects
+description: "Arduino Simple Field Oriented Control (FOC) library ."
+nav_order: 9
+permalink: /mini_example
+grand_parent: Arduino SimpleFOClibrary
+---
+
+
+# Position control example | | |
+
+
+# Connecting everything together
+
+Pin `12` is not a real ground pin. As no power is transferred through the mini's `GND` pin then we can use pin `12` to approximate the `GND` pin by declaring it as digital output and setting it to `LOW`. This technique might not always work though. If you start seeing that your motor vibrates, even in the open loop control mode, then you should ditch this approach and connect the mini's `GND` pin to the Arduino UNO's `GND` pin. The vibrations should then stop completely. ++ + +### Small motivation :D +
For more configuration parameters of the encoders please check the Encoder class docs.
+
+
+## Motor code
+First we need to define the `BLDCMotor` class with the number od pole pairs (`11`)
+```cpp
+// define BLDC motor
+BLDCMotor motor = BLDCMotor(11);
+```
+If you are not sure what your pole pairs number is please check the find_pole_pairs.ino example.
+
+
+Next we need to define the `BLDCDriver3PWM` class with the PWM pin numbers of the motor and the driver enable pin
+```cpp
+// define BLDC driver
+BLDCDriver3PWM driver = BLDCDriver3PWM(11, 10, 9, 8);
+```
+
+Then in the `setup()` we configure first the voltage of the power supply if it is not `12` Volts and init the driver.
+```cpp
+// power supply voltage
+// default 12V
+driver.voltage_power_supply = 12;
+driver.init();
+```
+Additionally we add the code to declare the pin `12` ad digital output set to `LOW` to be used as a common ground signal. In the `setup` we add
+```cpp
+pinMode(12,OUTPUT); // declares pin 12 as output and sets it to LOW
+```
+
+Then we tell the motor which control loop to run by specifying the `motor.controller` variable.
+```cpp
+// set control loop type to be used
+// MotionControlType::torque
+// MotionControlType::velocity
+// MotionControlType::angle
+motor.controller = MotionControlType::angle;
+```
+Now we configure the velocity PI controller parameters
+```cpp
+// velocity PI controller parameters
+// default P=0.5 I = 10
+motor.PID_velocity.P = 0.2;
+motor.PID_velocity.I = 20;
+
+//default voltage_power_supply
+motor.voltage_limit = 6;
+```
+Additionally we can configure the Low pass filter time constant `Tf`
+```cpp
+// velocity low pass filtering
+// default 5ms - try different values to see what is the best.
+// the lower the less filtered
+motor.LPF_velocity.Tf = 0.02;
+```
+Finally we configure position P controller gain and the velocity limit variable.
+```cpp
+// angle P controller
+// default P=20
+motor.P_angle.P = 20;
+// maximal velocity of the position control
+// default 20
+motor.velocity_limit = 4;
+```
+For more information about the angle control loop parameters please check the doc.+ +Next we connect the encoder and the driver to the motor, do the hardware init and init of the Field Oriented Control. +```cpp +// link the motor to the sensor +motor.linkSensor(&encoder); +// link the motor to the driver +motor.linkDriver(&driver); + +// initialize motor +motor.init(); +// align encoder and start FOC +motor.initFOC(); +``` +The last peace of code important for the motor is of course the FOC routine in the `loop` function. +```cpp +void loop() { +// iterative FOC function +motor.loopFOC(); + +// iterative function setting and calculating the angle/position loop +// this function can be run at much lower frequency than loopFOC function +motor.move(); +} +``` +That is it, let's see the full code now! +
For more configuration parameters and control loops please check the BLDCMotor class doc.
+
+## Full Arduino code
+To the full code I have added a small serial [commander interface](commander_interface), to be able to change position/angle target value in real time.
+
+```cpp
+#include 
| | |
+
+
+# Connecting everything together
+
For more configuration parameters of the encoders please check the Encoder class docs.
+
+
+## Motor code
+First we need to define the `BLDCMotor` class with the number od pole pairs (`11`)
+```cpp
+// define BLDC motor
+BLDCMotor motor = BLDCMotor(11);
+```
+If you are not sure what your pole pairs number is please check the find_pole_pairs.ino example.
+
+
+Next we need to define the `BLDCDriver3PWM` class with the PWM pin numbers of the motor and the driver enable pin
+```cpp
+// define BLDC driver
+BLDCDriver3PWM driver = BLDCDriver3PWM(13, 12, 11, 10);
+```
+
+Then in the `setup()` we configure first the voltage of the power supply if it is not `12` Volts and init the driver.
+```cpp
+// power supply voltage
+// default 12V
+driver.voltage_power_supply = 12;
+driver.init();
+```
+
+Then we tell the motor which control loop to run by specifying the `motor.controller` variable.
+```cpp
+// set control loop type to be used
+// MotionControlType::torque
+// MotionControlType::velocity
+// MotionControlType::angle
+motor.controller = MotionControlType::angle;
+```
+Now we configure the velocity PI controller parameters
+```cpp
+// velocity PI controller parameters
+// default P=0.5 I = 10
+motor.PID_velocity.P = 0.2;
+motor.PID_velocity.I = 20;
+
+//default voltage_power_supply
+motor.voltage_limit = 6;
+```
+Additionally we can configure the Low pass filter time constant `Tf`
+```cpp
+// velocity low pass filtering
+// default 5ms - try different values to see what is the best.
+// the lower the less filtered
+motor.LPF_velocity.Tf = 0.02;
+```
+Finally we configure position P controller gain and the velocity limit variable.
+```cpp
+// angle P controller
+// default P=20
+motor.P_angle.P = 20;
+// maximal velocity of the position control
+// default 20
+motor.velocity_limit = 4;
+```
+For more information about the angle control loop parameters please check the doc.+ +Next we connect the encoder and the driver to the motor, do the hardware init and init of the Field Oriented Control. +```cpp +// link the motor to the sensor +motor.linkSensor(&encoder); +// link the motor to the driver +motor.linkDriver(&driver); + +// initialize motor +motor.init(); +// align encoder and start FOC +motor.initFOC(); +``` +The last peace of code important for the motor is of course the FOC routine in the `loop` function. +```cpp +void loop() { +// iterative FOC function +motor.loopFOC(); + +// iterative function setting and calculating the angle/position loop +// this function can be run at much lower frequency than loopFOC function +motor.move(); +} +``` +That is it, let's see the full code now! +
For more configuration parameters and control loops please check the BLDCMotor class doc.
+
+## Full Arduino code
+To the full code I have added a small serial [commander interface](commander_interface), to be able to change position/angle target value in real time.
+
+```cpp
+#include -NEW RELEASE π’: SimpleFOClibrary v2.2.2 see release
--
+ +- GenericCurrentSense bugfix and testing
-- bugfix leonardo #170
-- bugfix - no index search after specifying natural direction
-- Low level API restructuring -
--
-- Driver API
-- Current sense API
-- New debugging interface - see in docs -
--
-- Static class SimpleFOCDebug
-- CurrentSense API change - added method
-linkDriver()- see in docs- Low-side current sensing - see in docs -
--
-- ESP32 generic support for multiple motors
-- Added low-side current sensing support for stm32 - only one motor -
--
-- f1 family
-- f4 family
-- g4 family
-- New appraoch for current estimation for torque control using voltage - see in docs -
--
-- Support for motor KV rating - back emf estimation
-- Using motor phase resistance
-- KV rating and phase resistance used for open-loop current limiting as well - see in docs
-++ +NEWS π’: SimpleFOClibrary has been published in the Journal of Open Source Software read more
+ +SimpleFOC: A Field Oriented Control (FOC) Library for Controlling Brushless Direct Current (BLDC) and Stepper Motors.
+A. Skuric, HS. Bank, R. Unger, O. Williams, D. GonzΓ‘lez-Reyes
+Journal of Open Source Software, 7(74), 4232
++-## Arduino SimpleFOClibrary v2.2.2 +## Arduino SimpleFOClibrary v2.2.3 This video demonstrates the Simple FOC library basic usage, electronic connections and shows its capabilities.NEW RELEASE π’: SimpleFOClibrary v2.2.3 see release
+- stm32 low-side current sensing + - g4 supported + - thoroughly tested f1/f4/g4 - [#187](https://github.com/simplefoc/Arduino-FOC/issues/187) + - bg431b: added support for VBAT and TEMPERATURE readings [#222](https://github.com/simplefoc/Arduino-FOC/pull/222) +- bugfixing + - leonardo + - mega2560 [#190](https://github.com/simplefoc/Arduino-FOC/issues/190) + - inline current sense without driver [#188](https://github.com/simplefoc/Arduino-FOC/issues/188) + - bg431b support current sense fix [#210](https://github.com/simplefoc/Arduino-FOC/pull/210) + - `StepperDriver4PWM` wrong init [#182](https://github.com/simplefoc/Arduino-FOC/issues/182) + - open loop back-emf voltage issue [#219](https://github.com/simplefoc/Arduino-FOC/issues/219) + - SAMD51 compile issue [#217](https://github.com/simplefoc/Arduino-FOC/issues/217) + - ESP32-S3 compile issue [#198](https://github.com/simplefoc/Arduino-FOC/issues/198) + - ESP32 compile issue [#208](https://github.com/simplefoc/Arduino-FOC/issues/208), [#207](https://github.com/simplefoc/Arduino-FOC/issues/207) + - magnetic sensor direction finding more robust [#173](https://github.com/simplefoc/Arduino-FOC/issues/173), [#164](https://github.com/simplefoc/Arduino-FOC/pull/164) + - `StepDirListener` improved timing [#169](https://github.com/simplefoc/Arduino-FOC/issues/169), [#209](https://github.com/simplefoc/Arduino-FOC/pull/209) + - `HallSensor` velocity calculation fix [#192](https://github.com/simplefoc/Arduino-FOC/issues/192) +- API changes + - `setPhaseVoltage` is now public function + - `getVelocity` can now be called as many times as necessary - [see in docs](encoder#standalone-sensor) + - it recalculates the velocity if the time between calls is longer then `min_elapsed_time` - default 0.1ms + - `HallSensor` velocity calculation outlier removal using max expected velocity `velocity_max` - [see in docs](hall_sensors#step-21-velocity-outlier-removal) + - BG431 board can be used only with `LowsideCurrentSense` class! - [see in docs](current_sense#current-sensing-support-per-mcu-architecture) + - `initFOC` fails if current sense not initialised - [see in docs](bldcdriver3pwm#step-23-initialisation) + - driver and current sense have to be well initialised for `initFOC` to start - [see in docs](bldcmotor#step-6-align-motor-and-all-the-sensors---field-oriented-control-init) + - `cs.init()` and `driver.init()` return `1` if well initialised and `0` if failed