docs: add API description for pulse width modulation peripheral
Signed-off-by: Michal Lenc <michallenc@seznam.cz>
This commit is contained in:
Michal Lenc
Alan Carvalho de Assis
parent
4d9e346ef4
commit
f525bc2802
@ -32,3 +32,181 @@ Files supporting PWM can be found in the following locations:
|
|||||||
in ``arch/<architecture>/src/<hardware>``
|
in ``arch/<architecture>/src/<hardware>``
|
||||||
directory for the specific processor ``<architecture>`` and for
|
directory for the specific processor ``<architecture>`` and for
|
||||||
the specific ``<chip>`` PWM peripheral devices.
|
the specific ``<chip>`` PWM peripheral devices.
|
||||||
|
|
||||||
|
Application Level Interface
|
||||||
|
===========================
|
||||||
|
|
||||||
|
The first necessary thing to be done in order to use the PWM driver in an
|
||||||
|
application is to include the header file for the NuttX timer driver. It contains
|
||||||
|
the Application Level Interface to the PWM driver. To do so, include:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#include <nuttx/timers/pwm.h>
|
||||||
|
|
||||||
|
PWM driver is registered as a POSIX character device file into ``/dev``
|
||||||
|
namespace. It is necessary to open the device to get a file descriptor for
|
||||||
|
further operations.
|
||||||
|
|
||||||
|
The PWM is accessed only through ``ioctl`` interface, functions ``read``
|
||||||
|
and ``write`` does not have any affect. Following ``ioctl`` commands are
|
||||||
|
available:
|
||||||
|
|
||||||
|
* :c:macro:`PWMIOC_SETCHARACTERISTICS`
|
||||||
|
* :c:macro:`PWMIOC_GETCHARACTERISTICS`
|
||||||
|
* :c:macro:`PWMIOC_START`
|
||||||
|
* :c:macro:`PWMIOC_STOP`
|
||||||
|
|
||||||
|
.. c:macro:: PWMIOC_SETCHARACTERISTICS
|
||||||
|
|
||||||
|
The ``PWMIOC_SETCHARACTERISTICS`` command sets PWM characteristics such as
|
||||||
|
frequency, duty cycle, dead times and so on. These characteristics are
|
||||||
|
set through ``pwm_info_s`` structure.
|
||||||
|
|
||||||
|
.. c:struct:: pwm_info_s
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
struct pwm_info_s
|
||||||
|
{
|
||||||
|
/* Frequency of the pulse train */
|
||||||
|
uint32_t frequency;
|
||||||
|
#ifdef CONFIG_PWM_MULTICHAN
|
||||||
|
/* Per-channel output state */
|
||||||
|
struct pwm_chan_s channels[CONFIG_PWM_NCHANNELS];
|
||||||
|
#else
|
||||||
|
/* Duty of the pulse train, "1"-to-"0" duration.
|
||||||
|
* Maximum: 65535/65536 (0x0000ffff)
|
||||||
|
* Minimum: 1/65536 (0x00000001)
|
||||||
|
*/
|
||||||
|
ub16_t duty;
|
||||||
|
#ifdef CONFIG_PWM_DEADTIME
|
||||||
|
/* Dead time value for main output */
|
||||||
|
ub16_t dead_time_a;
|
||||||
|
/* Dead time value for complementary output */
|
||||||
|
ub16_t dead_time_b;
|
||||||
|
#endif
|
||||||
|
#ifdef CONFIG_PWM_PULSECOUNT
|
||||||
|
/* The number of pulse to generate. 0 means to
|
||||||
|
* generate an indefinite number of pulses
|
||||||
|
*/
|
||||||
|
uint32_t count;
|
||||||
|
#endif
|
||||||
|
/* Channel polarity */
|
||||||
|
uint8_t cpol;
|
||||||
|
/* Disabled channel polarity */
|
||||||
|
uint8_t dcpol;
|
||||||
|
#endif /* CONFIG_PWM_MULTICHAN */
|
||||||
|
/* User provided argument to be used in the lower half */
|
||||||
|
FAR void *arg;
|
||||||
|
};
|
||||||
|
|
||||||
|
Structure ``pwm_chan_s`` holds the representation of one PWM channel
|
||||||
|
if multiple channels are used ( ``CONFIG_PWM_MULTICHAN`` is set).
|
||||||
|
|
||||||
|
.. c:struct:: pwm_chan_s
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
struct pwm_chan_s
|
||||||
|
{
|
||||||
|
/* Duty of the pulse train, "1"-to-"0" duration.
|
||||||
|
* Maximum: 65535/65536 (0x0000ffff)
|
||||||
|
* Minimum: 1/65536 (0x00000001)
|
||||||
|
*/
|
||||||
|
ub16_t duty;
|
||||||
|
#ifdef CONFIG_PWM_OVERWRITE
|
||||||
|
/* Channel overwrite */
|
||||||
|
bool ch_outp_ovrwr;
|
||||||
|
/* Channel overwrite value */
|
||||||
|
bool ch_outp_ovrwr_val;
|
||||||
|
#endif
|
||||||
|
#ifdef CONFIG_PWM_DEADTIME
|
||||||
|
/* Dead time value for main output */
|
||||||
|
ub16_t dead_time_a;
|
||||||
|
/* Dead time value for complementary output */
|
||||||
|
ub16_t dead_time_b;
|
||||||
|
#endif
|
||||||
|
/* Channel polarity */
|
||||||
|
uint8_t cpol;
|
||||||
|
/* Disabled channel polarity */
|
||||||
|
uint8_t dcpol;
|
||||||
|
/* Channel number */
|
||||||
|
int8_t channel;
|
||||||
|
};
|
||||||
|
|
||||||
|
Apart from duty cycle and frequency, the ``ioctl`` command allows to
|
||||||
|
set many other PWM characteristics. These functionalities might not be
|
||||||
|
supported by all PWM controllers and user should always refer to target
|
||||||
|
documentation in this case.
|
||||||
|
|
||||||
|
If ``CONFIG_PWM_OVERWRITE`` is set and ``ch_outp_ovrwr`` is true, it is
|
||||||
|
possible to overwrite channel output with value set in ``ch_outp_ovrwr_val``.
|
||||||
|
Configuration option ``CONFIG_PWM_DEADTIME`` and fields ``dead_time_a``
|
||||||
|
and ``dead_time_b`` provides an option to set dead time between complementary
|
||||||
|
outputs. This instructs the driver to automatically insert output activation
|
||||||
|
delay for complementary PWM outputs and is useful for H-bridge motor control
|
||||||
|
for example.
|
||||||
|
|
||||||
|
User may also set default channel polarity ``cpol`` and disabled channel
|
||||||
|
polarity ``dcpol``. If set to zero, default controller values (or values
|
||||||
|
determined in the configuration) are used. Following defines can be used
|
||||||
|
to set the polarities:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
/* Not defined, the default output state is arch dependant */
|
||||||
|
#define PWM_CPOL_NDEF 0
|
||||||
|
/* Logical zero */
|
||||||
|
#define PWM_CPOL_LOW 1
|
||||||
|
/* Logical one */
|
||||||
|
#define PWM_CPOL_HIGH 2
|
||||||
|
|
||||||
|
/* Not defined, the default output state is arch dependant */
|
||||||
|
#define PWM_DCPOL_NDEF 0
|
||||||
|
/* Logical zero */
|
||||||
|
#define PWM_DCPOL_LOW 1
|
||||||
|
/* Logical one */
|
||||||
|
#define PWM_DCPOL_HIGH 2
|
||||||
|
|
||||||
|
.. c:macro:: PWMIOC_GETCHARACTERISTICS
|
||||||
|
|
||||||
|
Command ``PWMIOC_GETCHARACTERISTICS`` operates the same way as
|
||||||
|
``PWMIOC_SETCHARACTERISTICS`` but it obtains currently set values
|
||||||
|
instead of setting them.
|
||||||
|
|
||||||
|
.. c:macro:: PWMIOC_START
|
||||||
|
|
||||||
|
The ``PWMIOC_START`` command starts the pulsed output. Characteristics
|
||||||
|
of PWM channels should be set before this operation.
|
||||||
|
|
||||||
|
.. c:macro:: PWMIOC_STOPS
|
||||||
|
|
||||||
|
The ``PWMIOC_STOPS`` command stops the pulsed output.
|
||||||
|
|
||||||
|
Application Example
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
An example application can be found in ``nuttx-apps`` repository under the
|
||||||
|
path ``examples/pwm``.
|
||||||
|
|
||||||
|
.. code-block :: bash
|
||||||
|
|
||||||
|
nsh> pwm
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
=============
|
||||||
|
|
||||||
|
This section describes common PWM configuration in ``Kconfig``. The reader
|
||||||
|
should refer to target documentation for target specific configuration.
|
||||||
|
|
||||||
|
PWM is enabled by ``CONFIG_PWM`` configuration option. Option
|
||||||
|
``CONFIG_PWM_MULTICHAN`` selects support for multiple channels for one PWM
|
||||||
|
instance. If multiple channels are used, configuration option
|
||||||
|
``CONFIG_PWM_NCHANNELS`` defines the maximum number of channels per instance.
|
||||||
|
Each timer/controller may support fewer output channels than this value.
|
||||||
|
|
||||||
|
Generation of pin overwrite is enabled by ``CONFIG_PWM_OVERWRITE`` option.
|
||||||
|
This supports generation of a pin overwrite with 0 or 1 without the need to
|
||||||
|
wait for an end of cycle.
|
||||||
|
|
||||||
|
The ``CONFIG_PWM_DEADTIME`` option brings the possibility to introduce
|
||||||
|
dead time values between complementary PWM outputs.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user