ST / X_NUCLEO_IHM04A1

Library used to control ST Nucleo Evaluation board IHM04A1, based on L6206 motor control driver.

Dependencies:   ST_INTERFACES

Dependents:   HelloWorld_IHM04A1 RoboCane_Motore arm_dcmotor_can arm_linear_can_2 ... more

Fork of X_NUCLEO_IHM04A1 by ST Expansion SW Team

Motor Control Library

Library to handle the X-NUCLEO-IHM04A1 Motor Control Expansion Board based on the L6206 component.

It allows a complete management of the L6206 by providing a complete APIs.

The key features of the library are :

  • Configuration of the L6206 (bridges inputs and enabling signals, bridges paralleling)
  • FLAG interrupts handling (overcurrent and thermal alarms reporting)
  • Handling of up to two bidirectional Brush DC motors or up to 4 unidirectional Brush DC motors depending of the bridges paralleling configuration
  • Nucleo and expansion board configuration (GPIOs, PWMs, IRQs…)

To use the L6206 driver library, the user first has to call its initialization method which:

  • Setups the required GPIOs to handle the bridges enable pins, the FLAG interrupt which reports overcurrent detection or thermal protection.
  • Loads the driver parameters with initial values configured by the user or with their predefined values from “l6206_target_config.h”, in order to program the PWMs frequency of the bridges inputs, the bridges paralleling configuration, the number and the type (bidirectional or unidirectional) of brush DC motors.

Once the initialization is done, the user can modify the driver parameters by calling specific functions to change the bridges paralleling configuration, types and numbers of motors or the PWMs frequency.

The user can also write callback functions and attach them to:

  • The flag interrupt handler depending on the actions he wants to perform when an overcurrent or a thermal alarm is reported.
  • The Error handler which is called by the library when it reports an error.

Then, the user can drive the different brush DC motors by requesting to run in a specified direction and by changing the maximal speed. When a motor is requested to run, the corresponding bridge is automatically enabled.

A motion command can be stopped at any moment:

  • Either by a hard stop which immediately stops the motor.
  • Or by a hardHiz command which immediately stops the motor and disables the bridge which is used by the motor.

The library also provides functions to disable or enable the bridges independently from the run or stop commands.

Arduino Connector Compatibility Warning

Using the X-NUCLEO-IHM04A1 expansion board with the NUCLEO-F429ZI requires adopting the following patch:

  • to connect with a wire the PB_4 Nucleo pin to the IN1A expansion board pin;
  • to connect with a wire the PC_7 Nucleo pin to the IN2A expansion board pin;
  • to connect with a wire the PA_15 Nucleo pin to the IN1B expansion board pin;
  • to connect with a wire the PB_3 Nucleo pin to the IN2B expansion board pin.


Board configuration for HelloWorld_IHM04A1 example

/media/uploads/brdirais/drive4brushdcmotor_ihm04a1.png

Diff: Components/l6206/l6206_class.h

Revision:
1:2597a6165252
Parent:
0:2cb6ce8e07bd
Child:
2:65057305b86e
--- a/Components/l6206/l6206_class.h	Tue May 03 11:16:57 2016 +0000
+++ b/Components/l6206/l6206_class.h	Tue May 17 09:45:13 2016 +0000
@@ -172,101 +172,222 @@
 	 *     return COMPONENT_EnableFeature();                                  *
 	 *   }                                                                    *
 	 *------------------------------------------------------------------------*/
+	 
+    /**
+     * @brief  Initializing the component.
+     * @param  init Pointer to device specific initalization structure.
+     * @retval "0" in case of success, an error code otherwise.
+     */
 	virtual int Init(void *init = NULL)
 	{
 		return (int) L6206_Init((void *) init);
 	}
-
+	
+    /**
+     * @brief  Getting the ID of the component.
+     * @param  id Pointer to an allocated variable to store the ID into.
+     * @retval "0" in case of success, an error code otherwise.
+     */
 	virtual int ReadID(uint8_t *id = NULL)
 	{
 		return (int) L6206_ReadId((uint8_t *) id);
 	}
 
+
+	/**
+ 	* @brief  Attaches a user callback to the error Handler.
+ 	* The call back will be then called each time the library detects an error
+ 	* @param[in] callback Name of the callback to attach to the error Hanlder
+ 	* @retval None
+ 	*/
 	virtual void AttachErrorHandler(void (*callback)(uint16_t error))
 	{
 		L6206_AttachErrorHandler((void (*)(uint16_t error)) callback);
 	}
 
+
+	/**
+ 	* @brief  Attaches a user callback to the flag Interrupt
+ 	* The call back will be then called each time the status 
+ 	* flag pin will be pulled down due to the occurrence of 
+ 	* a programmed alarms ( OCD, thermal alert)
+ 	* @param[in] callback Name of the callback to attach 
+ 	* to the Flag Interrupt
+ 	* @retval None
+ 	*/
 	virtual void AttachFlagInterrupt(void (*callback)(void))
 	{
 		L6206_AttachFlagInterrupt((void (*)(void)) callback);
 	}
 
+	/**
+ 	* @brief  Returns the current speed of the specified motor
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @retval current speed in % from 0 to 100
+ 	*/
 	virtual uint16_t GetCurrentSpeed(uint8_t motorId)
 	{
 		return (uint16_t) L6206_GetCurrentSpeed((uint8_t) motorId);
 	}
 
+	/**
+ 	* @brief Returns the device state
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @retval State (STEADY or INACTIVE)
+ 	*/
 	virtual motorState_t GetDeviceState(uint8_t motorId)
 	{
 		return (motorState_t) L6206_GetDeviceState((uint8_t) motorId);
 	}
 
+	/**
+ 	* @brief Returns the FW version of the library
+ 	* @retval L6206_FW_VERSION
+ 	*/
 	virtual uint8_t GetFwVersion(void)
 	{
 		return (uint8_t) L6206_GetFwVersion();
 	}
 
+	/**
+ 	* @brief  Returns the max  speed of the specified motor
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @retval maxSpeed in % from 0 to 100
+ 	*/
 	virtual uint16_t GetMaxSpeed(uint8_t motorId)
 	{
 		return (uint16_t) L6206_GetMaxSpeed((uint8_t) motorId);
 	}
 
+	/**
+ 	* @brief  Stops the motor without disabling the bridge
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @retval none
+ 	*/
 	virtual void HardStop(uint8_t motorId)
 	{
 		L6206_HardStop((uint8_t) motorId);
 	}
 
+	/**
+ 	* @brief  Runs the motor
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @param[in] direction FORWARD or BACKWARD
+ 	* @retval None
+ 	* @note  For unidirectionnal motor, direction parameter has no effect
+ 	*/
 	virtual void Run(uint8_t stepCount, motorDir_t direction)
 	{
 		L6206_Run((uint8_t) stepCount, (motorDir_t) direction);
 	}
 
+	/**
+ 	* @brief  Changes the max speed of the specified device
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @param[in] newMaxSpeed in % from 0 to 100
+ 	* @retval true if the command is successfully executed, else false
+ 	*/
 	virtual bool SetMaxSpeed(uint8_t motorId, uint16_t newMaxSpeed)
 	{
 		return (bool) L6206_SetMaxSpeed((uint8_t) motorId, (uint16_t) newMaxSpeed);
 	}
 
+	/**
+ 	* @brief Disable the specified bridge
+ 	* @param[in] bridgeId (from 0 for bridge A to 1 for bridge B)
+ 	* @retval None
+ 	* @note  When input of different brigdes are parallelized 
+ 	* together, the disabling of one bridge leads to the disabling
+ 	* of the second one
+ 	*/
 	virtual void CmdDisable(uint8_t bridgeId)
 	{
 		L6206_DisableBridge((uint8_t) bridgeId);
 	}
 
+	/**
+ 	* @brief Enable the specified bridge
+ 	* @param[in] bridgeId (from 0 for bridge A to 1 for bridge B)
+ 	* @retval None
+ 	* @note  When input of different brigdes are parallelized 
+ 	* together, the enabling of one bridge leads to the enabling
+ 	* of the second one
+ 	*/
 	virtual void CmdEnable(uint8_t bridgeId)
 	{
 		L6206_EnableBridge((uint8_t) bridgeId);
 	}
 
+	/**
+ 	* @brief  Get the status of the bridge enabling of the corresponding bridge
+ 	* @param[in] bridgeId from 0 for bridge A to 1 for bridge B
+ 	* @retval State of the Enable&Flag pin of the corresponding bridge (1 set, 0 for reset)
+  	*/
 	virtual uint16_t CmdGetStatus(uint8_t bridgeId)
 	{
 		return (uint16_t) L6206_GetBridgeStatus((uint8_t) bridgeId);
 	}
 
+	/**
+ 	* @brief  Immediatly stops the motor and disable the power bridge
+ 	* @param[in] motorId from 0 to MAX_NUMBER_OF_BRUSH_DC_MOTORS 
+ 	* @retval None
+ 	* @note  if two motors uses the same power bridge, the 
+ 	* power bridge will be disable only if the two motors are stopped
+ 	*/
 	virtual void CmdHardHiZ(uint8_t motorId)
 	{
 		L6206_HardHiz((uint8_t) motorId);
 	}
-
+	
+	/**
+ 	* @brief Error handler which calls the user callback (if defined)
+ 	* @param[in] error Number of the error
+ 	* @retval None
+ 	*/
 	virtual void ErrorHandler(uint16_t error)
 	{
 		L6206_ErrorHandler((uint16_t) error);
 	}
 
+	/**
+ 	* @brief Set dual full bridge parallelling configuration
+ 	* @param[in] newConfig bridge configuration to apply from 
+ 	* dualFullBridgeConfig_t enum
+ 	* @retval None
+ 	*/
 	virtual void SetDualFullBridgeConfig(uint8_t newConfig)
 	{
 		L6206_SetDualFullBridgeConfig((uint8_t) newConfig);
 	}
 
+	/**
+ 	* @brief  Get the PWM frequency of the specified bridge 
+ 	* @param[in] bridgeId 0 for bridge A, 1 for bridge B
+ 	* @retval Freq in Hz
+ 	*/
 	virtual uint32_t GetBridgeInputPwmFreq(uint8_t bridgeId)
 	{
 		return (uint32_t) L6206_GetBridgeInputPwmFreq((uint8_t) bridgeId);
 	}
 
+	/**
+ 	* @brief  Changes the PWM frequency of the bridge input
+ 	* @param[in] bridgeId 0 for bridge A, 1 for bridge B
+ 	* @param[in] newFreq in Hz
+ 	* @retval None
+ 	*/
 	virtual void SetBridgeInputPwmFreq(uint8_t bridgeId, uint32_t newFreq)
 	{
 		L6206_SetBridgeInputPwmFreq((uint8_t) bridgeId, (uint32_t) newFreq);
 	}
 
+	/**
+ 	* @brief  Sets the number of devices to be used
+ 	* @param[in] nbDevices (from 1 to MAX_NUMBER_OF_DEVICES)
+ 	* @retval TRUE if successfull, FALSE if failure, attempt to set a number of
+ 	* devices greater than MAX_NUMBER_OF_DEVICES
+ 	*/
 	virtual bool SetNbDevices(uint8_t nbDevices)
 	{
 		return (bool) L6206_SetNbDevices((uint8_t) nbDevices);
@@ -308,10 +429,10 @@
 
 	/**
      * @brief  Enabling the FLAG interrupt handling.
-     * @param  None.
+     * @param[in]  bridgeId 0 for bridge A, 1 for bridge B
      * @retval None.
      */
-    void EnableFlagIRQ(uint8_t bridgeId)
+    virtual void EnableFlagIRQ(uint8_t bridgeId)
     {
 		if (bridgeId == BRIDGE_A)
 		{
@@ -327,10 +448,10 @@
 
     /**
      * @brief  Disabling the FLAG interrupt handling.
-     * @param  None.
+     * @param[in]  bridgeId 0 for bridge A, 1 for bridge B
      * @retval None.
      */
-    void DisableFlagIRQ(uint8_t bridgeId)
+    virtual void DisableFlagIRQ(uint8_t bridgeId)
     {
     	if (bridgeId == BRIDGE_A)
     		flag_A_irq.fall(NULL);
@@ -341,21 +462,7 @@
 
 	/*** Public In/Out Related Methods ***/
 
-    void OutVal( uint8_t bridgeId, uint8_t val)
-    {
-    	if( bridgeId == BRIDGE_A)
-    	{
-    		EN_flag_A.output();
-    		EN_flag_A.mode(PullNone);
-    		EN_flag_A.write(val);
-    	}
-    	else
-    	{
-    		EN_flag_B.output();
-    		EN_flag_B.mode(PullNone);
-    		EN_flag_B.write(val);
-    	}
-    }
+
 
 protected:
 
@@ -412,24 +519,68 @@
 	 * Implement here other I/O methods beyond those already implemented      *
 	 * above, which are declared extern within the component's header file.   *
 	 *------------------------------------------------------------------------*/
+	 
+	/**
+     * @brief      Utility function to set or unset EN pin for Bridge A or Bridge B.
+     * @param[out] none
+     * @param[in]  bridgeId 0 for bridge A, 1 for bridge B
+     * @retval     none
+     */
+	void L6206_OutVal( uint8_t bridgeId, uint8_t val)
+    {
+    	if( bridgeId == BRIDGE_A)
+    	{
+    		EN_flag_A.output();
+    		EN_flag_A.mode(PullNone);
+    		EN_flag_A.write(val);
+    	}
+    	else
+    	{
+    		EN_flag_B.output();
+    		EN_flag_B.mode(PullNone);
+    		EN_flag_B.write(val);
+    	}
+    }
+	 
+    /**
+     * @brief  Making the CPU wait.
+     * @param  None.
+     * @retval None.
+     */
 	void L6206_Board_Delay(uint32_t delay)
 	{
 		wait_ms(delay);
 	}
 
+	/**
+ 	* @brief Disable the specified bridge
+ 	* @param[in] bridgeId (from 0 for bridge A to 1 for bridge B)
+ 	* @retval None
+ 	* @note  When input of different brigdes are parallelized 
+ 	* together, the disabling of one bridge leads to the disabling
+ 	* of the second one
+ 	*/
 	void L6206_Board_DisableBridge(uint8_t bridgeId)
 	{
 		DisableFlagIRQ(BRIDGE_A);
 		DisableFlagIRQ(BRIDGE_B);
 
 		__disable_irq();
-		OutVal( bridgeId, 0);
+		L6206_OutVal( bridgeId, 0);
 		__enable_irq();
 	}
 
+	/**
+ 	* @brief Enable the specified bridge
+ 	* @param[in] bridgeId (from 0 for bridge A to 1 for bridge B)
+ 	* @retval None
+ 	* @note  When input of different brigdes are parallelized 
+ 	* together, the enabling of one bridge leads to the enabling
+ 	* of the second one
+ 	*/
 	void L6206_Board_EnableBridge(uint8_t bridgeId, uint8_t addDelay)
 	{
-		OutVal( bridgeId, 1);
+		L6206_OutVal( bridgeId, 1);
 
   		if (addDelay != 0)
 			{
@@ -439,7 +590,11 @@
   		EnableFlagIRQ( bridgeId);
 	}
 	
-
+	/**
+ 	* @brief  Returns the FLAG pin state.
+ 	* @param[in]  bridgeId (from 0 for bridge A to 1 for bridge B)
+ 	* @retval The FLAG pin value.
+ 	*/
 	uint32_t L6206_Board_GetFlagPinState(uint8_t bridgeId)
 	{
   		if (bridgeId == 0)
@@ -454,6 +609,10 @@
   		}
 	}
 
+	/**
+ 	* @brief  Initiliases the GPIOs used by the L6206s
+ 	* @retval None
+  	*/
 	void L6206_Board_GpioInit(void)
 	{
 		/* Init bridge Enable */
@@ -472,8 +631,15 @@
 
 	}
 
-	/** Board PWM management **/
-
+	/**
+	* @brief  Sets the frequency of PWM used for bridges inputs
+ 	* @param[in] bridgeInput 0 for input 1A, 1 for input 2A,
+  	* 2 for input 1B,  3 for input 2B
+ 	* @param[in] newFreq in Hz
+ 	* @param[in] duty Duty cycle
+ 	* @retval None
+ 	* @note The frequency is directly the current speed of the device
+ 	*/
 	void L6206_Board_PwmSetFreq(uint8_t bridgeInput, uint32_t newFreq, uint8_t duty)
 	{
         /* Computing the period of PWM. */
@@ -513,6 +679,12 @@
   		}
 	}
 
+	/**
+ 	* @brief  Reset the PWM for the specified brigde input
+ 	* @param[in] bridgeInput 0 for input 1A, 1 for input 2A,
+ 	* 2 for input 1B, 3 for input 2B
+ 	* @retval None
+  	*/
 	void L6206_Board_PwmDeInit(uint8_t bridgeInput)
 	{
 		  switch (bridgeInput)
@@ -536,10 +708,22 @@
 		  }
 	}
 
+	/**
+ 	* @brief  Set the PWM frequency the for the specified bridge input
+ 	* @param[in] bridgeInput 0 for input 1A, 1 for input 2A,
+ 	* 2 for input 1B, 3 for input 2B
+ 	* @retval None
+  	*/
 	void L6206_Board_PwmInit(uint8_t bridgeInput)
 	{
 	}
 
+	/**
+ 	* @brief  Stops the PWM uses for the specified brige input
+ 	* @param[in] bridgeInput 0 for input 1A, 1 for input 2A,
+ 	* 2 for input 1B, 3 for input 2B
+ 	* @retval None
+ 	*/
 	void L6206_Board_PwmStop(uint8_t bridgeInput)
 	{
 		  switch (bridgeInput)