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>``
|
||||
directory for the specific processor ``<architecture>`` and for
|
||||
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