Bring clear instructions and parameters for PWM usage

[FDelporte]

It's probably me, but I find PWM the hardest IO Type to use... It's unclear how to map GPIO pin numbers to chip/channel parameters for hardware PWM, how to configure on different types of RPi's, etc.

Current documentation: https://www.pi4j.com/documentation/io-types/pwm/

I guess this can be fixed by extending the documentation and parameters in the following way:

Hardware PWM

Only a limited number of hardware-accelerated PWMs are available. These can be checked with:

$ ls -l /sys/class/pwm/
pwmchip0

$ pinctrl | grep PWM
18: a3    pd | lo // GPIO18 = PWM0_CHAN2
19: a3    pd | lo // GPIO19 = PWM0_CHAN3
45: op dh pd | hi // FAN_PWM/GPIO45 = output

Implementation

• Parameters should be chip and channel
• The plugin PWM provider must throw an error if chip and channel are not provided with PwmType.HARDWARE
• The plugin PWM provider should log a warning if a bcm is provided with PwmType.HARDWARE
• Implementation changes needed in the plugins to allow this usage
• @DigitalSmile can we add com.pi4j.plugin.ffm.providers.pwm.PwmFFMSoftware ?

# Chip can be retrieved with a helper method
# This returns 0 for non-RP1 (pre-RPi 5) and correct number for RP1 (RPi 5)
var chip = PwmChipUtil.getPWMChip();

# Example based on the output above for `GPIO18 = PWM0_CHAN2`
var pwmConfig = Pwm.newConfigBuilder(pi4j)
    .pwmType(PwmType.HARDWARE)
    .chip(chip)
    .channel(2)
    .build();

Documentation

• Describe how to enable, configure, and use HARDWARE PWM with chip and channel on different RPi models
• Create JBang example
• Document what happens if you try to use hardware PWM on a non-hardware PWM pin
• Document frequency/duty cycle usage and limitations

Software PWM

Software PWM is implemented entirely in code, and it can generate PWM signals on any pin that supports general-purpose output. But it has less accurate timing due to CPU load and OS scheduling.

Implementation

• Parameters should be bcm
• The plugin PWM provider throw an error if ibcm is not provided with PwmType.SOFTWARE
• The plugin PWM provider should log a warning if anything else than bcm is provided with PwmType.SOFTWARE
• Implementation changes needed in the plugins to allow this usage

# Example based on the output above for `GPIO18 = PWM0_CHAN2`
var pwmConfig = Pwm.newConfigBuilder(pi4j)
    .pwmType(PwmType.SOFTWARE)
    .bcm(18)
    .build();

Documentation

• Describe how to use SOFTWARE PWM with bcm
• Create JBang example

[eitch]

I like this, as i have also always stayed away from PWM for this reason =)

For software, shouldn't it say:
The builder should throw an error if anything other than bcm is provided with PwmType.SOFTWARE?

[taartspi]

Chip(0). We did the utility to find the correct chip as it may change in the Rp1 device tree. I know Nick was against using the utility within ffm as he wants ffm generic I thought we discussed an api above the ffm provider and it would use the utility.

[FDelporte]

@taartspi, correct, we have PwmChipUtil.getPWMChipForRP1 in core library. Let me try out if I can extend this further to provide more generic use. Does this mean the chip parameter is only needed on RPi 5 with RP1?

[taartspi]

I believe yes. Only a Rp1 constraint. I should have opened an issue against ffm when this was discussed to avoid this late discussion

[DigitalSmile]

can we add com.pi4j.plugin.ffm.providers.pwm.PwmFFMSoftware ?

In a recent kernels there is a software PWM driver built in, which is way more faster than any user-space implementations. I did not check it, but I think It could be the way to go.

raspberrypi/linux#6450