vgavara / arduino-tb6612fng Goto Github PK

Right now custom PWM frequency on SAMD21 based hardware is being managed using the SAMD21 Turbo PWM library. It allowed a fast integration of custom PWM features, but also arises some problems:

• Part of the library code is not being used
• Resolution is limite to 1000 steps, though ArduinoTB6612FNG supports resolutions up to 16 bit and, moreover, the resolutions under 23kHz frequencies are >= 2048 steps (see Wiki).
• Imposes a library dependency

The SAMD21 Turbo PWM library strictly relevant code must be extracted, simplified and stored in a new include file. Documentation making reference to the SAMD21 Turbo PWM dependency must be updated.

Now a SpinPoint.speed equal to zero in a SpinMap means stating an invalid speed value to the Motor class, since Motor rejects this value.

The Spinner class must be upgraded to stop the motor when a speed equal to zero is reached. The documentation must be properly upgraded.

As project grows the documentation is requiring a dedicated location out of the README.md file.

• A documentation MD file per class must be created. All those files must be stored in /docs/classes.
• Datasheets must be stored in docs/datasheets
• Class reference documentation must be removed from the /README.md file

As described in the issue #3, it is possible to increase the PWM frequency of the Arduino outputs and, therefore, achieving a better motor management.

• The class Motor must be upgraded to support specifying an optional, custom PWM frequency.
• Only SAMD21 based Arduinos are being supported (those with the symbol __SAMD21G18A__ defined) by using the library SAMD21 turbo PWM.
• The code size footprint of this feature must be minimized, so a symbol must be defined (TB6612FNG_ENABLE_CUSTOM_PWM_FREQUENCY) in header in order to enable it (by default it will be disabled).

Enhance spinner class to give support to multi-linear maps, ie, maps with more than one linear spin path. A linear spin path represents a linear acceleration between two spin points.

Develop a Stepper class to use the TB6612FNG as driver of a two-phase permanent-magnet stepper motors. It will allow:

• Running a stepper stating its direction and speed.
• Stopping it.

An example of custom PWM called Motor02 has been created in the context of the task feature #30.

Documentation must be created for this example following the style of the existing examples.

Create a class that added acceleration functionalities to the Motor class.

Specifically, this class must allow accelerating/deccelerating the rotation of a motor in a lineal way, ie, changing its speed from a start speed to a target speed in a given amount of time.

Additional information

• The class could be called Spinner
• It should inherit from the Motor class
• It should implement a spin function with four arguments: direction, start speed, end speed, time (ms)

Issue #34 gave support to custom PWM to the Spinner class. Now an example exposing this new feature must be created.

• Create an example exposing the new custom PWM features of the Spinner class.
• Create example documentation.
• Update the examples general documentation, if needed.

Spinner constructor documentation defines only one constructor with two examples, one for the case of not using callbacks and other when using callbacks.

However, two constructors should be documented, since they have different paramenters, and the existing examples should be assigned to the right constructor

Create a README.md document in examples/Spinner containing an index of examples and a brief explanation of each one.

Current codebase with members not documented, or not documented with JSDoc must be migrated to JSDoc.

• Public members must be fully documented
• Private members should be documented

Now all the operation to the driver are performed via the Motor class. Specifically, the standBy operation, that is not related to a motor but to the whole driver is also performed in this class. This is a weird design that must be corrected by giving the whole driver a class entity.

• Create a Driver class for supporting the driver specific operations, ie, the standBy operation.
• Remove the support to standBy from the Motor class.
• Create and update the documentation.

As stated in this article, higher PWM frequencies improve the motor performance.

Arduino default PWM frequencies (usually below 1kHz) are low compared with the max frequency that the TB6612FNG can drive (100 kHz), so there is room for increasing the PWM frequency and therefore improving the motor handling.

As described here and here, it is possible to modify the default Arduino PWM frequency. Moreover, there exist specific libraries for managing PWM frequencies for specific Arduino processors (Arduino SAMD21 turbo PWM library for managing PWM in SAMD21G-based Arduinos).

This matter must be studied and a document must be written and stored as repository wiki entry. The document must cover the different options for different processors, putting special attention in identifying existing libraries covering the max amount of Arduino processors.

Issue #30 gave custom PWM features to the Motor class. The Spinner class, fully based on Motor class, must support those features too.

• All the references to Motor speeds must be updated to support the new 16-bit format.
• The spinner examples must be updated.
• The spinner documentation must be updated.

As result of the works on issues #30 and #3, it is required to create a Wiki document exposing the way how the support to custom PWM frequency on SAMD21 hardware is being developed.

This document will expose how the library SAMD21_turbo_PWM will be integrated to minimize its impact in the current library architecture while simplifying its usage.

A Bezier map is that defining a curved acceleration path, that in last term describes a variable acceleration between and initial and final speed.

A new spinner class must be developed supporting Bezier maps, containing a set of Spin points intended as the control points of a Bezier curve.

Performance and code size, respectivelly, must be prioritized.

Interesting links:

• Implementing Bezier curve
• De Casteljau's Algorithm and Bézier Curves

Now the field time of the struct SpinPoint is defined as unsigned int, what makes it hardware platform dependant, as exposed here.

SpinPoint.time must be hardware agnostic by defining it as uint16_t. Documentation must be properly upgraded.

Complete the Spinner class with one more example aborting the spinning when the map reached a certain point. Don't base the example in callbacks but in checking the results returned by spin() function.

Create a README.md file per example and add the required graphic documents (see Motor examples)

Special care must be put in adding a subdirectory per example (as Spinner/SpinnerExample01) to be aligned with the directory structure expected by Arduino IDE.

Add "At a Glance" and "Getting Started" sections to /README.md to make easier the library adoption process.

• "At a Glance" must show quick examples of the library usage.
• "Getting Started" must include information about downloading and installing the library. It must also include an easy roadmap to start with: first checking the examples and then the reference documentation.