An alternative way of dealing with PWM pins

[MCUdude]

This is something that has bugged me for quite a while with MegaCoreX. PWM pin routing is somewhat flexible on these modern AVRs, but I've been forced to place them in fixed positions that overlap the least with other peripherals. I think it's a shame that the possibility of re-routing the PWM output is thrown out the window. It is possible to reconfigure the PORTMUX and the various timers yourself, but it takes a lot of time and effort to dive into the datasheet to figure everything out when you just want a simple PWM signal on a different pin.

My idea is to supplement the Arduino framework with a few additional functions that will make routing and minor reconfiguring much easier. I'm not talking about full-blown TCA and TCB reconfiguring, just the possibility to re-route, change the resolution, and clock prescaler.

I've come up with the following functions and enums to pass along:

void pwmWrite(pwm_timers_t pwmTimer, uint16_t value, timers_route_t timerRoute = ROUTE_UNTOUCHED);
void pwmPrescaler(pwm_timers_t pwmTimer, timers_prescaler_t prescaler);
void pwmSetResolution(pwm_timers_t pwmTimer, uint8_t maxValue);

// Located in pins_arduino.h
enum pwm_timers_t : uint8_t {
  TCA0_0 = 0,
  TCA0_1 = 1,
  TCA0_2 = 2,
  TCA0_3 = 3,
  TCA0_4 = 4,
  TCA0_5 = 5,
  TCB_0  = 6,
  TCB_1  = 7,
  TCB_2  = 8,
  TCB_3  = 9,
};

// Located in pins_arduino.h
enum timers_route_t : uint8_t {
  ROUTE_TCA0_PORTA = 0x40,
  ROUTE_TCA0_PORTB = 0x41,
  ROUTE_TCA0_PORTC = 0x42,
  ROUTE_TCA0_PORTD = 0x43,
  ROUTE_TCA0_PORTE = 0x44,
  ROUTE_TCA0_PORTF = 0x45,
  ROUTE_TCB0_PA2   = 0x00,
  ROUTE_TCB0_PF4   = 0x01,
  ROUTE_TCB1_PA3   = 0x10,
  ROUTE_TCB1_PF5   = 0x11,
  ROUTE_TCB2_PC0   = 0x20,
  ROUTE_TCB2_PB4   = 0x21,
  ROUTE_TCB3_PB5   = 0x30,
  ROUTE_TCB3_PC1   = 0x31,
  ROUTE_UNTOUCHED  = 0x80,
};

// Located in Arduino.h
enum timers_prescaler_t : uint8_t {
  TCA_DIV1    = 0x00,
  TCA_DIV2    = 0x02,
  TCA_DIV4    = 0x04,
  TCA_DIV8    = 0x06,
  TCA_DIV16   = 0x08,
  TCA_DIV64   = 0x0A,
  TCA_DIV256  = 0x0C,
  TCA_DIV1024 = 0x0E,
  TCB_DIV1    = 0x00,
  TCB_DIV2    = 0x20,
  TCB_CLKTCA  = 0x40,
};

The development branch for this is located here. Again, the goal is not to expose every timer function imaginable; it's just a set of functions to make it easier to reconfigure the 8-bit PWM outputs. The reason why I'm using enums is to force the user to actually use this and hopefully throw an error if a non-compatible constant is used.

Let's say you want PWM output on pin PB2 using timer TCA0 and a custom prescaler. Easy!

uint8_t duty = 0x80;
pwmPrescaler(TCA0_2, TCA_DIV8);
pwmWrite(TCA0_2, duty, ROUTE_TCA0_PORTF);

@SpenceKonde I'd like to hear your thoughts on this. Have you been in a situation where you'd like to re-map PWM pins?

[MCUdude]

I've updated the extended API documentation where the new PWM related functions have been added:
https://github.com/MCUdude/MegaCoreX/blob/pwm_write/Extended-API.md

[SpenceKonde]

You haven't seen my PORTMUX aware PWM system? I just overhauled it (though there may still be issues relating to the recent changes - as you know a lot of changes have gone in in a short time to get the new parts working.

On TCA/TCE (caveat: more work on TCE needed, but not much), and where the remapping works, TCD as well. analogWrite() checks the PORTMUX if appropriate. If the portmux is pointed at the pin, it does it's thing, otherwise does digital write and treats it as a non-PWM pin

TCF is also PORTMUX aware (it was easy to do; untested same as TCE of course; verifying the PWM is next)

It's been in for TCA and TCD for ages, especially for TCA0 where the payoff is highest

TCBs don't have any portmux awareness (it's fixed as always, but they only have 2 options each, and one of those options is usually clearly better); the extent of the test I use is, it sees that it's that TCB's pin, and checks the timer's CTRLB to see if it's in PWM mode; if it's not, we treat as digitalWrite() because the user has configured the timer for something other than PWM). The TCBs are not very good PWM timers.

I put some helper functions in a library, but like, you don't even need that for the normal use case of setting different pins in setup and not changing them at runtime.

For MCX, you've only got the one timer, TCA0 right? that's a much simpler case - you'd just need to check if the TCAROUTEA == digitalPinToPort(), and if the digitalPinToBitPosition() was less than 6, it's got TCA pwm, if not, check the table for the TCBs (I do TCE/TCA with that sort of logic, while the rest uses the classic macro; there's also a new digitalPinToTimerNow() that uses the same logic as the PWM code to determine what timer is on a pin.