FEAT added magnetic sensors + prepared for v1.6.0

askuric · askuric · commit 09b5adc9f3d0 · 2020-10-11T10:39:45.000+02:00
diff --git a/_includes/js/custom.js b/_includes/js/custom.js
@@ -32,7 +32,8 @@ var defines =[
     "EN_GATE ",
     "M_PWM",
     "M_OC",
-    "OC_ADJ"
+    "OC_ADJ",
+    "SPI_MODE0"
 ]
 
 var classNames = [
@@ -121,7 +122,9 @@ var structNames = [
     "Pullup",
     "Quadrature",
     "ControlType",
-    "FOCModulationType"
+    "FOCModulationType",
+    "MagneticSensorSPIConfig_s",
+    "MagneticSensorI2CConfig_s"
 ];
 var structProps = [
     "EXTERN",
diff --git a/docs/simplefoc_library/code/communication.md b/docs/simplefoc_library/code/communication.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Motor commands
-parent: Using the Code
+parent: Writing the Code
 nav_order: 6
 permalink: /communication
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
diff --git a/docs/simplefoc_library/code/index.md b/docs/simplefoc_library/code/index.md
@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Using the Code
+title: Writing the Code
 nav_order: 6
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /code
diff --git a/docs/simplefoc_library/code/monitoring.md b/docs/simplefoc_library/code/monitoring.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Monitoring
-parent: Using the Code
+parent: Writing the Code
 nav_order: 5
 permalink: /monitoring
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> 
diff --git a/docs/simplefoc_library/code/motion_control/angle.md b/docs/simplefoc_library/code/motion_control/angle.md
@@ -2,7 +2,7 @@
 layout: default
 title: Position Control 
 parent: Motion Control
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 nav_order: 3
diff --git a/docs/simplefoc_library/code/motion_control/angle_openloop.md b/docs/simplefoc_library/code/motion_control/angle_openloop.md
@@ -2,7 +2,7 @@
 layout: default
 title: Position Open-Loop
 parent: Motion Control
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /angle_openloop
diff --git a/docs/simplefoc_library/code/motion_control/index.md b/docs/simplefoc_library/code/motion_control/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Motion Control
-parent: Using the Code
+parent: Writing the Code
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /motion_control
 nav_order: 3
diff --git a/docs/simplefoc_library/code/motion_control/index_search.md b/docs/simplefoc_library/code/motion_control/index_search.md
@@ -2,7 +2,7 @@
 layout: default
 title: Index Search loop 
 parent: Motion Control
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 nav_order: 4
diff --git a/docs/simplefoc_library/code/motion_control/velocity.md b/docs/simplefoc_library/code/motion_control/velocity.md
@@ -2,7 +2,7 @@
 layout: default
 title: Velocity Control
 parent: Motion Control
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /velocity_loop
diff --git a/docs/simplefoc_library/code/motion_control/velocity_openloop.md b/docs/simplefoc_library/code/motion_control/velocity_openloop.md
@@ -2,7 +2,7 @@
 layout: default
 title: Velocity Open-Loop
 parent: Motion Control
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /velocity_openloop
diff --git a/docs/simplefoc_library/code/motion_control/voltage.md b/docs/simplefoc_library/code/motion_control/voltage.md
@@ -2,7 +2,7 @@
 layout: default
 title: Torque Control
 parent: Motion Control
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /voltage_loop
diff --git a/docs/simplefoc_library/code/motor.md b/docs/simplefoc_library/code/motor.md
@@ -2,7 +2,7 @@
 layout: default
 title: Motor & Driver
 nav_order: 2
-parent: Using the Code
+parent: Writing the Code
 permalink: /motor_initialization
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 ---
@@ -82,6 +82,7 @@ You can set them by changing the `motor.foc_modulation` variable:
 // FOCModulationType::SpaceVectorPWM;
 motor.foc_modulation = FOCModulationType::SpaceVectorPWM;
 ```
+<blockquote class="warning"> StepperMotor class has only Sinusoidal PWM modulation implemented for the moment <a href="https://github.com/simplefoc/Arduino-FOC/releases"> <i class="fa fa-tag">current version</i></a>. </blockquote>
 
 The voltage used for the motor and sensor alignment set the variable `motor.voltage_sensor_align`:
 ```cpp
diff --git a/docs/simplefoc_library/code/sensors/encoder.md b/docs/simplefoc_library/code/sensors/encoder.md
@@ -5,7 +5,7 @@ description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /encoder
 nav_order: 1
 parent: Position Sensor
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 ---
 
diff --git a/docs/simplefoc_library/code/sensors/hall_sensor.md b/docs/simplefoc_library/code/sensors/hall_sensor.md
@@ -5,7 +5,7 @@ description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /hall_sensors
 nav_order: 3
 parent: Position Sensor
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 ---
 
diff --git a/docs/simplefoc_library/code/sensors/index.md b/docs/simplefoc_library/code/sensors/index.md
@@ -4,7 +4,7 @@ title: Position Sensor
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 permalink: /sensors
 nav_order: 1
-parent: Using the Code
+parent: Writing the Code
 has_children: True
 has_toc: False
 grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
diff --git a/docs/simplefoc_library/code/sensors/magnetic_sensor.md b/docs/simplefoc_library/code/sensors/magnetic_sensor.md
@@ -2,7 +2,7 @@
 layout: default
 title: Magnetic sensor
 parent: Position Sensor
-grand_parent: Using the Code
+grand_parent: Writing the Code
 grand_grand_parent: Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span>
 description: "Arduino Simple Field Oriented Control (FOC) library ."
 nav_order: 2
@@ -38,12 +38,22 @@ The parameters of the class are
 - `bit_resolution` - resolution of your sensor (number of bits of the sensor internal counter register) and your
 - `angle register` - register number containing angle value. <br>The default `angle_register` number is set to `0x3FFF` as it is the angle register for most of the low cost AS5048/AS5047 sensors. 
 
-Finally after the initialization the only thing you need to do afterwards is to call the `init()` function. This function prepares the SPI interface and initializes the sensor hardware. So your magnetic sensor initialization code will look like:
+Additionally the library allows you to configure SPI communication clock speed and SPI mode by setting the variables:
+```cpp
+// spi mode (phase/polarity of read/writes) i.e one of SPI_MODE0 | SPI_MODE1 (default) | SPI_MODE2 | SPI_MODE3
+sensor.spi_mode = SPI_MODE0;
+// speed of the SPI clock signal - default 1MHz
+sensor.clock_speed = 500000;
+```
+
+Finally after the configuration the only thing you need to do is to call the `init()` function. This function prepares the SPI interface and initializes the sensor hardware. So your magnetic sensor initialization code will look like:
 ```cpp
 MagneticSensorSPI sensor = MagneticSensorSPI(10, 14, 0x3FFF);
 
 void loop(){
   ...
+  sensor.spi_mode = SPI_MODE0; // spi mode - OPTIONAL
+  sensor.clock_speed = 500000; // spi clock frequency - OPTIONAL
   sensor.init();
   ...
 }
@@ -62,7 +72,49 @@ void loop(){
 }
 ```
 
-Please check the `magnetic_sensor_spi_example.ino` example to see more about it.
+### Quick configuration for common sensors
+
+For the most common SPI magnetic sensors, the library provides the simplified configuration constructor. Namely for AS5047/AS5147 14-bit SPI sensors and MA70 14-bit SSI sensor.
+```cpp
+// instance of AS5047/AS5147 sensor
+MagneticSensorSPI sensor = MagneticSensorSPI(10, AS5147_SPI);
+// instance of MA730 sensor
+MagneticSensorSPI sensor = MagneticSensorSPI(10, MA730_SPI);
+```
+If wish to implement your own quick configuration structure, you will need to create an instance of the structure:
+```cpp
+struct MagneticSensorSPIConfig_s  {
+  int bit_resolution;
+  int angle_register;
+  int spi_mode; // default SPI_MODE0
+  long clock_speed;  // default 1MHz
+  int data_start_bit; // default 13
+  int command_rw_bit; // default 14
+  int command_parity_bit; // default 15
+};
+```
+and provide it to the constructor, here is an example:
+```cpp
+// 12 bit, 0x3FFF angle register, spi mode 1, 1MHz, default start bit, rw command, and parity bit 
+MagneticSensorSPIConfig_s MySensorConfig = {
+  .bit_resolution=12, 
+  .angle_register=0x3FFF, 
+  .spi_mode=SPI_MODE1, 
+  .clock_speed=1000000, 
+  .data_start_bit=13,
+  .command_rw_bit=14,
+  .command_parity_bit=15
+  }; 
+
+// the sensor class with desired sensor configuration
+MagneticSensorSPI sensor = MagneticSensorSPI(10, MySensorConfig);
+void setup(){
+  sensor.init();
+  ...
+}
+```
+
+Please check the `magnetic_sensor_spi_example.ino` example for a quick test of your sensor. All the features of SPI magnetic sensors are implemented in the `MagneticSensorSPI.cpp/h` files. 
 
 
 ## I2C communication `MagneticSensorI2C`
@@ -103,16 +155,33 @@ Example MSB/LSB division:
 </ul>
 </blockquote>
 
-Finally after the initialization the only thing you need to do afterwards is to call the `init()` function. This function prepares the SPI interface and initializes the sensor hardware. So your magnetic sensor initialization code will look like:
+Additionally, the library enables you to configure the I2C bus clock speed `clock_speed`, and change SDA `sda_pin` and SCL `scl_pin` pin locations. 
+```cpp
+// I2C bus clock frequency - default 400kHz
+sensor.clock_speed = 1000000;
+// the pin used for i2c data - default 14 (Arduino UNO,MEGA,STM32 NUCLEO)
+sensor.sda_pin = 10;
+// the pin used for i2c clock - default 15 (Arduino UNO,MEGA,STM32 NUCLEO)
+sensor.scl_pin = 11; 
+```
+
+Finally, after the configuration, you just call the `init()` function. This function prepares the SPI interface and configures the sensor hardware. So your magnetic sensor initialization code will look like:
 ```cpp
 MagneticSensorI2C sensor = MagneticSensorI2C(0x36, 12, 0x0E, 4);
 
 void loop(){
   ...
+  sensor.clock_speed = 1000000; // change I2C bus clock frequency - OPTIONAL
+  sensor.sda_pin = 10; // change i2c data pin - OPTIONAL
+  sensor.scl_pin = 11; // change i2c clock pin - OPTIONAL
   sensor.init();
   ...
 }
 ```
+<blockquote class="warning"><p class="heading">BEWARE: SDA ans SCL pin change</p>
+Arduino Devices based on ATMega328 and ATMega2560 chips do not support SDA and SCL pin change. For these devices you will need to use either pins 14,15 or A4,A5.<br>  STM32 devices and ESP32 boards fully support changing the pins location.
+</blockquote>
+
 
 If you wish to use more than one magnetic sensor using SPI interface, make sure your sensors have different addresses, here is a simple example:
 ```cpp
@@ -127,9 +196,45 @@ void loop(){
 }
 ```
 
-Please check the `magnetic_sensor_i2_example.ino` example to see more about it.
+###  Quick configuration for common sensors
 
+For the most common I2C magnetic sensors, the library provides the simplified configuration constructor. Namely for AS5600 12-bit sensor and AS5048 14-bit sensor.
+```cpp
+// instance of AS5600 sensor
+MagneticSensorI2C sensor2 = MagneticSensorI2C(AS5600_I2C);
+// instance of AS5048B sensor
+MagneticSensorI2C sensor2 = MagneticSensorI2C(AS5048_I2C);
+```
+If wish to implement your own quick configuration structure, you will need to create an instance of the structure:
+```cpp
+struct MagneticSensorI2CConfig_s  {
+  int chip_address;
+  int bit_resolution; 
+  int angle_register;
+  int data_start_bit; 
+  long clock_speed;  // default 400kHz
+};
+```
+and provide it to the constructor, here is an example:
+```cpp
+// configuration for AS5600 sensor
+MagneticSensorI2CConfig_s MySensorConfig = {
+  .chip_address = 0x36, 
+  .bit_resolution = 12, 
+  .angle_register=0x0E, 
+  .clock_speed=400000, 
+  .data_start_bit=11
+  }; 
+
+// the sensor class with desired sensor configuration
+MagneticSensorI2C sensor = MagneticSensorI2C(MySensorConfig);
+void setup(){
+  sensor.init();
+  ...
+}
+```
 
+Please check the `magnetic_sensor_i2_example.ino` example for a quick test of your sensor. All the features of I2C magnetic sensors are implemented in the `MagneticSensorI2C.cpp/h` files. 
 
 ## Analog output `MagneticSensorAnalog`
 In order to use your Analog output magnetic position sensor with <span class="simple">Simple<span class="foc">FOC</span>library</span> first create an instance of the `MagneticSensorAnalog` class:
@@ -205,6 +310,13 @@ class MagneticSensorI2C{
   	// shaft angle getter
     float getAngle();
 }
+class MagneticSensorAnalog{
+ public:
+    // shaft velocity getter
+    float getVelocity();
+  	// shaft angle getter
+    float getAngle();
+}
 ```
 
 Here is a quick example for the AS5047U magnetic sensor with SPI communication:
@@ -216,6 +328,8 @@ Here is a quick example for the AS5047U magnetic sensor with SPI communication:
 // bit_resolution  - sensor resolution
 // angle_register  - (optional) angle read register - default 0x3FFF
 MagneticSensorSPI as5047u = MagneticSensorSPI(10, 14, 0x3FFF);
+// or quick config
+MagneticSensorSPI as5047u = MagneticSensorSPI(10, AS4147_SPI);
 
 void setup() {
   // monitoring port
@@ -246,6 +360,8 @@ Here is a quick example for AS5600 magnetic sensor with I2C communication:
 //  angle_register_msb   - angle read register msb
 //  bits_used_msb        - number of used bits in msb register
 MagneticSensorI2C as5600 = MagneticSensorI2C(0x36, 12, 0x0E, 4);
+// or quick config
+MagneticSensorI2C as5047u = MagneticSensorI2C(AS5600_I2C);
 
 void setup() {
   // monitoring port
diff --git a/docs/simplefoc_library/digging_deeper/libray_source/index.md b/docs/simplefoc_library/digging_deeper/libray_source/index.md
@@ -10,7 +10,7 @@ has_children: True
 has_toc: false
 ---
 
-# Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> source code
+# Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> source code [v1.5.0](https://github.com/simplefoc/Arduino-FOC/releases)
 The arduino library code is organized into the standard [Arduino library structure](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). 
 The library contains main BLDC motor class `BLDCMotor` and  three sensor classes `Encoder`, `MagneticSensorSPI` and `MagneticSensorI2C` implementing the `Sensor` interface. Furthermore it has `FOCutils` file with all the necessary utility functions and `defaults.h` with all the default configuration variables.
 
diff --git a/docs/simplefoc_library/examples/position_control_example_nucleo.md b/docs/simplefoc_library/examples/position_control_example_nucleo.md
@@ -193,7 +193,7 @@ motor.command(serialReceiveUserCommand());
 ``` 
 And that is it, we everything configured and ready to go, let's see the full code!
 
-For more info about the [monitoring](monitoring) and [motor commands](communicaiton) visit the [using the code section](code).
+For more info about the [monitoring](monitoring) and [motor commands](communicaiton) visit the [Writing the Code section](code).
 
 ## Full Arduino code
 
diff --git a/docs/simplefoc_library/index.md b/docs/simplefoc_library/index.md
@@ -138,7 +138,7 @@ Arduino <span class="simple">Simple<span class="foc">FOC</span>library</span> is
 
 [Find out more <i class="fa  fa-external-link"></i>](supported_hardware)
 
-## Using the code
+## Writing the Code
 This library code is written in a way to be as simple sa possible to use and to leave a lot of space for configuration and fine tuning for specific applications. 
 
 [Find out more <i class="fa  fa-external-link"></i>](code)
diff --git a/index.md b/index.md
