AVR: Customizing

µCNC for AVR can be configured/customized to fit different AVR powered boards other than Arduino UNO

Jump to section

• Understanding the HAL for AVR
  • Naming conventions
• Customizing boardmap
  • Configure IO pin
  • Input pin options
  • Configure communications
  • Configure pwm clock
  • Configure analog channel
  • Configure step generator timer

Understanding the HAL for AVR

µCNC for AVR is designed so that a single file defines the way the board links to the HAL interface and is then used by the core code to control the CNC machine. µCNC HAL uses some fixed naming conventions to map the MCU i/o to the core HAL and autogenerate the needed code.

Naming conventions

Output pins - special

• STEP# pin defines the step output pin that controls linear actuator driver.
  • STEP0 to STEP5 are the output pins to control the step signal up to 6 independent drivers.
  • STEP6 and STEP7 are the output pins used as shadow registers to drive dual drive linear actuators.
• DIR# pin defines the dir output pin that controls the linear actuator driver.
  • DIR0 to DIR5 are the output pins to control the direction signal up to 6 independent drivers
• STEPPER#_EN pin defines the enable output pin that controls the linear actuator driver.
  • STEPPER_EN to STEPPER5_EN are the output pins to control the enable signal up to 6 independent drivers.

Input pins - special

• LIMIT_# pin defines the input pin that controls end-stop switch detection.
  • LIMIT_X, LIMIT_Y, LIMIT_Z, LIMIT_A, LIMIT_B, LIMIT_C, LIMIT_X2, LIMIT_Y2 and LIMIT_Z2.
• ESTOP, SAFETY_DOOR, FHOLD and CS_RES pin defines the input pins that controls user actions and safety features.
• PROBE pin defines the input pin used for probing and tool length detection.

COM pins - special

• TX pin defines the UART port tx pin.
• RX pin defines the UART port rx.

Output pins - generic

• PWM# pin defines a pwm output pin.
  • PWM0 to PWM15 are the pwm output pins.
• DOUT# pin defines a generic output pin.
  • DOUT0 to DOUT15 are the generic output pins.

Input pins - generic

• ANALOG# pin defines an analog input pin.
  • ANALOG0 to ANALOG15 are the analog input pins.
• DIN# pin defines a generic input pin.
  • DIN0 to DIN15 are the generic input pins. pin.

Customizing boardmap

Taking the boardmap_grbl.h file inside src\hal\boards\avr folder, has an example lets walk through each section of the file.

Configure IO pin

An HAL pin need to be mapped to a physical IO pin. The way this is done is by defining the IO PORT and BIT. This must be performed for every used pin

//set pin D2 as STEP0 (output pin) 
#define STEP0_PORT D
#define STEP0_BIT 2
//set pin B1 as LIMIT_X (input pin) 
#define LIMIT_X_PORT B
#define LIMIT_X_BIT 1
//set pin B3 as PWM0 (pwm output pin) 
#define PWM0_PORT B
#define PWM0_BIT 3

Input pin options

All input pins can have a weak pull-up activated to drive them high if unconnected.

To activate this option to a pin just declare:

//activates LIMIT_X pin weak pull-up 
#define LIMIT_X_PULLUP

All pins all repeatedly read by a soft polling routine. But for special function pins an interrupt driven event to force a reading and respective action can be also activated. This causes the response to be immediate and not depend on the pin reading routine cycle. AVR has two types of input interrupts. The interrupt on change feature that can be configure up to 3 ports and also an external interrupt feature assigned to several pins on different ports (check the MCU datasheet for specifications). For Arduino UNO the pin mapping can be checked here.

Interrupt on change feature

1. The interrupt on change feature can be configured up to 3 ports on AVR (PCINT0-7, PCINT8-15 and PCINT16-23). For this you need to map in the HAL the PCINT#_PORT (# from 0-2) to the respective port. PCINT0_PORT handles (PCINT0-7), PCINT1_PORT handles (PCINT8-15) and PCINT2_PORT handles (PCINT16-23). For example:

//On Arduino UNO port B has PCINT0-7 interrupt on change feature so HAL's PCINT0_PORT must be correctly mapped to this port
#define PCINT0_PORT B

2. Now you can activate the interrupt on change feature on any pin of that port.

//activate interrupt on change feature on LIMIT_X that is tight to IO pin B3
#define LIMIT_X_ISR 0 //PCINT<0> ISR

External interrupt feature

To activate an INT# interrupt on an input pin just define the ISR to be the negative value of the (# + 1). For example (from boardmap file for RAMPS) to active INT5 interrupt feature available on pin E5 that is assigned to LIMIT_X just declare:

//activate external interrupt feature on LIMIT_X that is tight to IO pin E5
#define LIMIT_X_ISR -6 //INT<5> ISR => -(5 + 1)

Configure communications

Besides configuring TX and RX pin the number of the used USART/UART port must also be defined. The value must be equal to the USART port number. If not defined USART0 will be used by default.

//Use USART1
#define COM_PORT 0 //(USART0)

Configure pwm clock

To configure the pwm clock the used OCR# register and timer must be supplied. To find the used OCR# register and timer we must check the MCU datasheet. Looking at the pin mapping shown above for Arduino UNO and knowing that Grbl uses pin 11 (pin B3) has the spindle pwm control we can see that the pwm on that pin is generated via OC2A which in turn translates to Timer 2 OCR register A.

#define PWM0_OCR A
#define PWM0_TIMER 2

Just a quick note. Later the PWM0 is assigned to SPINDLE in the config.h but this the side of the code connection to the HAL.

Configure analog channel

Although not used anywhere inside µCNC reading analog pins is possible. Beside configuring the pin like an input pin, two more definitions are needed to configure the AVR analog reading. These are setting the channel and the desired prescaller for the conversion. For example on Arduino UNO the A4 (Analog channel 4) is on pin C4. To configure it as µCNC's ANALOG0 input add the following code to the boardmap file:

#define ANALOG0_BIT 4
#define ANALOG0_PORT C
#define ANALOG0_CHANNEL 4 //AVR channel 4
#define ANALOG0_PRESC 0 //set a value from 0 (prescaller 1) to 7 (prescaller (2^7=128)

To make a read just do

uint8_t value = mcu_get_analog(ANALOG0);

Configure step generator timer

All step and dir pins are modified inside a timer ISR (µCNC's heartbeat). For this a free (unused) 16-bit timer inside AVR must be chosen. By default Timer1 is used unless specified.

//Setup the Step Timer used has the heartbeat for µCNC
//Timer 1 is used by default
#define ITP_TIMER 1

//Setup the RTC Timer used by µCNC to provide an (mostly) accurate time base for all time dependent functions
//Timer 0 is set by default
#define RTC_TIMER 0