====== Motors ======

//Related to: [HW] [[en:hardware:homelab:motor]]//

This library contains functions to control different HomeLab motors. There are functions for DC, stepper and servo motors.

===== Data Types =====

  * **//prescale//** \\  PWM clock prescaler enumration data type. It determines the division factor of system clock. It is recommended to use the first two division factors. Options:
    * //TIMER2_NO_PRESCALE// - Division factor not used.
    * //TIMER2_PRESCALE_8// - Division factor 8.
    * //TIMER2_PRESCALE_64// - Division factor 64.
    * //TIMER2_PRESCALE_256// - Division factor 256.
    * //TIMER2_PRESCALE_1024// - Division factor 1024.

===== Functions =====

  * **//void dcmotor_init(unsigned char index)//** \\
    Initializes one of the DC motor controllers. Parameters:
    * //index// - Index of motor controller. 0 to 3.

  * **//void dcmotor_drive(unsigned char index, signed char direction)//** \\
    Drives one of the DC motor controllers. Parameters:
    * //index// - Index of motor controller. 0 to 3.
    * //direction// - Motor polarity. -1, 0 or +1. In case of 0 motor is stopped, otherwise it turns in given direction.

  * **//void dcmotor_drive_pwm_init(unsigned char index, timer2_prescale prescaler)//** \\     Initializes one of the DC motor controllers for speed control. In addition, you can set the appropriate prescaler, depending on the frequency of the PWM's you need. Parameters:
    * //index// - Index of motor controller. 0 to 3.
    * //prescaler// - Clock prescaler selection. Interruptions can occur very quickly upset the program of work. For example, when the UH sensor is used, it is necessary to set the prescaler TIMER2_PRESCALE_8. 

  * **//void dcmotor_drive_pwm(unsigned char index, signed char direction, unsigned char speed) //** \\
Drives one of the DC motor controllers. Motor rotates in a predetermined direction and speed. Parameters:
    * //index// - Index of motor controller. 0 to 3.
    * //direction// -  Motor polarity. -1 or +1. 
    * //speed// - Motor speed.  0 to 255. 0 the engine is stopped and the 255 is the maximum possible speed.

  * **//void unipolar_init(unsigned char index)//** \\
    Initializes one of the unipolar stepper motor controllers. Parameters:
    * //index// - Index of motor controller. 0 or 1.

  * **//void unipolar_halfstep(unsigned char index, signed char direction, unsigned short num_steps, unsigned char speed)//** \\
    Unipolar stepper motor half-stepping command. Functions is blocking as it is fulfilled as long as steps are done. Parameters:
    * //index// - Index of motor controller. 0 or 1.
    * //direction// - Directions of rotation. -1 or +1.
    * //num_steps// - Count of half-steps.
    * //speed// - Time of a single step in milliseconds.

  * **//void bipolar_init(void)//** \\
    Initializes bipolar stepper motor controller.

  * **//void bipolar_halfstep(signed char direction, unsigned short num_steps, unsigned char speed)//** \\
    Bipolar stepper motor half-stepping command. Functions is blocking as it is fulfilled as long as steps are done. Parameters:
    * //direction// - Directions of rotation. -1 or +1.
    * //num_steps// - Count of half-steps.
    * //speed// - Time of a single step in milliseconds.

  * **//void servomotor_init(unsigned char index)//** \\
    Initializes one of a servo motor PWM signal generations units in ATmega128 timer 1. PWM signal is 50 hz with high period of 1.5 ms ± 0.5 ms. Parameters:
    * //index// - Index of servo motor. 0 or 1.

  * **//void servomotor_position(unsigned char index, signed short position)//** \\
    Servo motor pulse width control command. If positioning servo motor is driven, its position is altered, if rotating one, its rotation speed is altered. Parameters:
    * //index// - Index of servo motor. 0 or 1.
    * //position// - Position or rotation speed. -100 to +100. 0 corresponds to stop.

===== Example =====

The following program demonstrates the usage of DC, stepper and servo motors.

<code c>
#include <homelab/module/motors.h>
 
int main(void)
{
	// DC motors initialization.
	dcmotor_init(0);
	dcmotor_init(1);

	// Bipolar stepper initialization.
	bipolar_init();

	// Servo motors initialization.
	servomotor_init(0);
	servomotor_init(1);

	// One DC motors drives forward, another in backward direction.
	dcmotor_drive(0, -1);
	dcmotor_drive(1, +1);

	// Rotating the stepper motor 100 steps in one direction
	// and then back with twice the speed.
	bipolar_halfstep(1, 100, 50);
	bipolar_halfstep(-1, 100, 25);

	// Rotating servo motors in opposite directions.
	servomotor_position(0, -100);
	servomotor_position(1, +100);
}
</code>

This example demonstrates the speed adjustments of a DC motor. 

<code c>
#include <homelab/module/motors.h>

int main(void)
{
        unsigned char speed = 0;
	
	// DC motors initialization
  	dcmotor_drive_pwm_init(0, TIMER2_NO_PRESCALE);

  	while(1)
  	{   	
		speed = 100;

		// DC motors drives predefined speed and direction.
		dcmotor_drive_pwm(0, 1, speed);			      
  	}
}
</code>