Skip to contentSkip to conversation

doc: document the pwm command

PATCH Superseded Emil Kronborg 2 participants 3 messages Jul 31, 2024 – Aug 1, 2024

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 doc: document the pwm command

---
Changes in v2:
- Fixed 'pwm enable' appearing twice in the examples section.
- Rebased on top of master.

 doc/usage/cmd/pwm.rst | 80 +++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst   |  1 +
 2 files changed, 81 insertions(+)
 create mode 100644 doc/usage/cmd/pwm.rst
doc/usage/cmd/pwm.rst new file +80 -0
new file mode 100644
index 000000000000..3562e50280e6
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+.. index::
+   single: pwm (command)
+
+pwm command
+===========
+
+Synopsis
+--------
+
+::
+
+    pwm invert <pwm_dev_num> <channel> <polarity> - invert polarity
+    pwm config <pwm_dev_num> <channel> <period_ns> <duty_ns> - config PWM
+    pwm enable <pwm_dev_num> <channel> - enable PWM output
+    pwm disable <pwm_dev_num> <channel> - disable PWM output
+
+
+Description
+-----------
+
+The ``pwm`` command is used to access and configure PWM (Pulse Width Modulation)
+signals. For all subcommands, the following arguments are common:
+
+pwm_dev_num
+    device number
+
+channel
+    channel on chosen device
+
+pwm invert
+----------
+
+The signal's active and inactive states are swapped.
+
+pwm config
+----------
+
+Configure the period and duty cycle in nanoseconds.
+
+pwm enable
+----------
+
+Enable output on the configured device and channel.
+
+pwm disable
+-----------
+
+Disable output on the configured device and channel.
+
+Examples
+--------
+
+Configure device 0 channel 0 to 50 kHz period and 70% duty cycle::
+
+    => pwm config 0 0 20000 14000
+
+Enable output on the configured device and channel::
+
+    => pwm enable 0 0 20000 14000
+
+Disable output on the configured device and channel::
+
+    => pwm disable 0 0 20000 14000
+
+Invert the signal on the configured device and channel::
+
+    => pwm invert 0 0 1
+
+Configuration
+-------------
+
+The ``pwm`` command is only available if CONFIG_CMD_PWM=y.
+
+Return value
+------------
+
+If the command succeeds, the return value ``$?`` is set to 0. If an error occurs, the
+return value ``$?`` is set to 1.
doc/usage/index.rst +1 -0
index 49b354e6ffd2..1adab5283950 100644
@@ -92,6 +92,7 @@ Shell commands
    cmd/pinmux
    cmd/printenv
    cmd/pstore
+   cmd/pwm
    cmd/qfw
    cmd/read
    cmd/reset

base-commit: 8877bc51a8a4d921ba2f163208b8b1a57ba47c18

Signature · 1 line
2.46.0
#2 lore raw
Quoted 8 lines · Quentin Schulz

Did you test this? It doesn't match the synopsis section, the help text

of the command and the source code.

Reading the code, pwm enable only expects two arguments, same for pwm disable, so I would assume that the following should be used instead:

Quoted 8 lines

pwm enable 0 0
pwm disable 0 0

Did we forget to fix the help text and I misread the code maybe?

Cheers,
Quentin

Hi Quentin,

I did indeed test it, and you are correct that pwm enable and disable only expect two arguments. The additional two arguments (20000 14000) were a leftover from copy-pasting that I forgot to delete.

You did not misread anything, but I sent out a v2 patch to address another issue before I got your email.

I will send a v3 patch, which:

- Changes the help text to be explicit about 20 us and 14 us for the period and duty cycle, respectively.
- Fixes pwm enable and disable to only expect 2 arguments.

Thanks again.

Signature · 1 line
Emil Kronborg