From fe17ec167bf0f6f868fde9019b38f077ae6d2181 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 15 Oct 2018 01:22:05 +1100 Subject: [PATCH 1/4] docs/machine: Specify new class machine.PWM. --- docs/library/machine.PWM.rst | 72 ++++++++++++++++++++++++++++++++++++ docs/library/machine.rst | 1 + 2 files changed, 73 insertions(+) create mode 100644 docs/library/machine.PWM.rst diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst new file mode 100644 index 0000000000000..62d5173f31c0e --- /dev/null +++ b/docs/library/machine.PWM.rst @@ -0,0 +1,72 @@ +.. currentmodule:: machine +.. _machine.PWM: + +class PWM -- pulse width modulation +=================================== + +This class provides pulse width modulation output. + +Example usage:: + + from machine import PWM + + pwm = PWM(pin) # create a PWM object on a pin + pwm.duty_u16(32768) # set duty to 50% + + # reinitialise with a period of 20ms, duty of 2ms + pwm.init(period=20, tick_hz=1000, duty_ticks=2) + + pwm.duty_ticks(3) # set duty to 3ms + + pwm.deinit() + +Constructors +------------ + +.. class:: PWM.init(dest, \*, freq, period, tick_hz, duty_ticks, duty_u16, block) + + Construct and return a new PWM object using the following parameters: + + - *dest* is the entity on which the PWM is output, which is usually a + `machine.Pin ` object, but a port may allow other values, + like integers. + - *freq* should be an integer which sets the frequency in Hz for the + PWM cycle. + - *period* should be an integer which sets the period of the PWM cycle. + The units of this are given by *tick_hz*. + - *tick_hz* gives the base unit by which *period* and *duty_ticks* + are measured. + - *duty_ticks* sets the duty cycle in ticks. + - *duty_u16* sets the duty cycle as a ratio ``duty_u16 / 65535``. + - *block* allows for finer control over the underlying PWM generator + that is used for this PWM object, and the values it takes are port + specific (this parameter may or may not be supported by a port). + + Only one of *freq* and *period* should be specified at a time. Setting these + values may affect other PWM objects if the objects share the same underlying + PWM generator (this is hardware specific). + + The value of *tick_hz* will be saved and reused by the ``PWM.duty_ticks`` + method. This value is unique to each PWM object. + +Methods +------- + +.. method:: PWM.init(\*, freq, period, tick_hz, duty_ticks, duty_u16) + + Modify settings for the PWM object. See the above constructor for details + about the parameters. + +.. method:: PWM.deinit() + + Disable the PWM output. + +.. method:: PWM.duty_ticks(ticks) + + Change the duty cycle of the output, with the argument *ticks* measured in + ``ticks_hz`` as set by the constructor or ``PWM.init``. For example, if + ``ticks_hz`` is 1000 then *ticks* is measured in milliseconds. + +.. method:: PWM.duty_u16(u16) + + Change the duty cycle of the output, measured as the ratio ``u16 / 65535``. diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 18dc6f2afaa59..5076dc30e059f 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -167,6 +167,7 @@ Classes machine.Pin.rst machine.Signal.rst machine.ADC.rst + machine.PWM.rst machine.UART.rst machine.SPI.rst machine.I2C.rst From 2f6124465fb9104e4ba54615606775f7321a7e50 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 21 Apr 2021 14:45:35 +1000 Subject: [PATCH 2/4] docs/library/machine: Update PWM to match rp2 implementation. Signed-off-by: Damien George --- docs/library/machine.PWM.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst index 62d5173f31c0e..03b3c24b83434 100644 --- a/docs/library/machine.PWM.rst +++ b/docs/library/machine.PWM.rst @@ -61,12 +61,35 @@ Methods Disable the PWM output. +.. method:: PWM.freq([value]) + + Get or set the current frequency of the PWM output. + + With no arguments the frequency in Hz is returned. + + With a single *value* argument the frequency is set to that value in Hz. The + method may raise a ``ValueError`` if the frequency is outside the valid range. + .. method:: PWM.duty_ticks(ticks) Change the duty cycle of the output, with the argument *ticks* measured in ``ticks_hz`` as set by the constructor or ``PWM.init``. For example, if ``ticks_hz`` is 1000 then *ticks* is measured in milliseconds. -.. method:: PWM.duty_u16(u16) +.. method:: PWM.duty_u16([value]) + + Get or set the current duty cycle of the PWM output, as an unsigned 16-bit + value in the range 0 to 65535 inclusive. + + With no arguments the duty cycle is returned. + + With a single *value* argument the duty cycle is set to that value, measured + as the ratio ``value / 65535``. + +.. method:: PWM.duty_ns([value]) + + Get or set the current duty cycle of the PWM output, as a value in nanoseconds. + + With no arguments the duty cycle in nanoseconds is returned. - Change the duty cycle of the output, measured as the ratio ``u16 / 65535``. + With a single *value* argument the duty cycle is set to that value. From 58399fe45ca05c64cc4633520df22f093bef1a0b Mon Sep 17 00:00:00 2001 From: Damien George Date: Thu, 22 Apr 2021 10:53:57 +1000 Subject: [PATCH 3/4] docs/library/machine: Remove period, ticks_hz and duty_ticks. Signed-off-by: Damien George --- docs/library/machine.PWM.rst | 38 +++++++++++------------------------- 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst index 03b3c24b83434..91433db9ba529 100644 --- a/docs/library/machine.PWM.rst +++ b/docs/library/machine.PWM.rst @@ -13,46 +13,36 @@ Example usage:: pwm = PWM(pin) # create a PWM object on a pin pwm.duty_u16(32768) # set duty to 50% - # reinitialise with a period of 20ms, duty of 2ms - pwm.init(period=20, tick_hz=1000, duty_ticks=2) + # reinitialise with a period of 200us, duty of 5us + pwm.init(freq=5000, duty_ns=5000) - pwm.duty_ticks(3) # set duty to 3ms + pwm.duty_ns(3000) # set duty to 3us pwm.deinit() Constructors ------------ -.. class:: PWM.init(dest, \*, freq, period, tick_hz, duty_ticks, duty_u16, block) +.. class:: PWM(dest, \*, freq, duty_u16, duty_ns) Construct and return a new PWM object using the following parameters: - *dest* is the entity on which the PWM is output, which is usually a - `machine.Pin ` object, but a port may allow other values, + :ref:`machine.Pin ` object, but a port may allow other values, like integers. - - *freq* should be an integer which sets the frequency in Hz for the + - *freq* should be an integer which sets the frequency in Hz for the PWM cycle. - - *period* should be an integer which sets the period of the PWM cycle. - The units of this are given by *tick_hz*. - - *tick_hz* gives the base unit by which *period* and *duty_ticks* - are measured. - - *duty_ticks* sets the duty cycle in ticks. - *duty_u16* sets the duty cycle as a ratio ``duty_u16 / 65535``. - - *block* allows for finer control over the underlying PWM generator - that is used for this PWM object, and the values it takes are port - specific (this parameter may or may not be supported by a port). + - *duty_ns* sets the duty cycle in nanoseconds. - Only one of *freq* and *period* should be specified at a time. Setting these - values may affect other PWM objects if the objects share the same underlying - PWM generator (this is hardware specific). - - The value of *tick_hz* will be saved and reused by the ``PWM.duty_ticks`` - method. This value is unique to each PWM object. + Setting *freq* may affect other PWM objects if the objects share the same + underlying PWM generator (this is hardware specific). + Only one of *duty_u16* and *duty_ns* should be specified at a time. Methods ------- -.. method:: PWM.init(\*, freq, period, tick_hz, duty_ticks, duty_u16) +.. method:: PWM.init(\*, freq, duty_u16, duty_ns) Modify settings for the PWM object. See the above constructor for details about the parameters. @@ -70,12 +60,6 @@ Methods With a single *value* argument the frequency is set to that value in Hz. The method may raise a ``ValueError`` if the frequency is outside the valid range. -.. method:: PWM.duty_ticks(ticks) - - Change the duty cycle of the output, with the argument *ticks* measured in - ``ticks_hz`` as set by the constructor or ``PWM.init``. For example, if - ``ticks_hz`` is 1000 then *ticks* is measured in milliseconds. - .. method:: PWM.duty_u16([value]) Get or set the current duty cycle of the PWM output, as an unsigned 16-bit From 7304486fc133fdfaef2327a5ef27327f6ebbe31d Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 23 Apr 2021 11:48:01 +1000 Subject: [PATCH 4/4] docs/library/machine: Reword duty cycle to pulse width for duty_ns. --- docs/library/machine.PWM.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst index 91433db9ba529..f2273d8b453da 100644 --- a/docs/library/machine.PWM.rst +++ b/docs/library/machine.PWM.rst @@ -16,7 +16,7 @@ Example usage:: # reinitialise with a period of 200us, duty of 5us pwm.init(freq=5000, duty_ns=5000) - pwm.duty_ns(3000) # set duty to 3us + pwm.duty_ns(3000) # set pulse width to 3us pwm.deinit() @@ -33,7 +33,7 @@ Constructors - *freq* should be an integer which sets the frequency in Hz for the PWM cycle. - *duty_u16* sets the duty cycle as a ratio ``duty_u16 / 65535``. - - *duty_ns* sets the duty cycle in nanoseconds. + - *duty_ns* sets the pulse width in nanoseconds. Setting *freq* may affect other PWM objects if the objects share the same underlying PWM generator (this is hardware specific). @@ -72,8 +72,8 @@ Methods .. method:: PWM.duty_ns([value]) - Get or set the current duty cycle of the PWM output, as a value in nanoseconds. + Get or set the current pulse width of the PWM output, as a value in nanoseconds. - With no arguments the duty cycle in nanoseconds is returned. + With no arguments the pulse width in nanoseconds is returned. - With a single *value* argument the duty cycle is set to that value. + With a single *value* argument the pulse width is set to that value.