Skip to content

Input Calibration

Jump to bottom Edit New page
Candas1 edited this page Mar 20, 2023 · 35 revisions

Input Calibration is required to identify:

  • the type of inputs you are using (normal pot, mid-resting pot, no input)
  • the range of your inputs (minimum and maximum values)
  • the middle value (e.g center of the joystick) for mid-resting pots

At startup, for safety reasons, the firmware won't enable the motors if the input is not very small (between -50 and 50).
If you don't hear a double beep after the Power On melody, it means the motors are not enabled as they would start to spin otherwise.
You need to calibrate your inputs either manually or with the auto-calibration.

Type of inputs

🔒 Disabled input(0)

This type of input has to be used if you don't need one of the inputs and want it to be ignored. The ouput will always be 0.
The skateboard variant for example is only using one input.

🎚️ Normal pot(1)

This type of input will be mapped to a positive ouput(voltage/speed/torque) only.

0----------> INPUT_MAX(1000)

The hovercar variant for example is using such inputs (throttle/brake handles or pedals).

🕹️ Mid-resting pot(2)

This type of input will be mapped to a positive and negative ouput(voltage/speed/torque) on each side of the resting/middle position.

INPUT_MIN(-1000) <----------0----------> INPUT_MAX(1000)

This enables forward/backward driving or left/right steering(voltage/speed mode) , or Throttle/Brake(torque mode) from the same input.
The Nunchuk variant is using such input types.

🎛️ Automatic(3)

This type of input will be automatically be identified when you proceed with the auto-calibration.
The ADC variant is using such input types.

ADC Protection

ADC Protection helps identify if wires are disconnected when using ADC control(ADC and HOVERCAR variants).
It identifies when the measured ADC value is below MIN - ADC_PROTECT_THRESH or above MAX + ADC_PROTECT_THRESH.
If detected, the board will enter the ADC timeout state and generate 2 beeps(low pitch).

Prerequisites are:

  • using pull down resistors so the input is pulled to ground/0V when the wire is disconnected
  • having your MIN/MAX values properly calibrated with manual or auto calibration
  • your input should have enough gap between 0 and MIN

0ADC/0V<--->MIN<---MID--->MAX<--->4095ADC/3.3V

The auto-calibration will let you know with a high pitch beep if the inputs can be protected, you can also see it in the debug output.
This is usually not the case with potentiometer that use the full 0-3.3v range.

Those are the parameters to adjust the ADC protection:

  • ADC_PROTECT_THRESH : to adjust the threshold below/above the MIN/MAX ADC values that will trigger ADC protection
  • ADC_PROTECT_TIMEOUT : number of wrong / missing input commands before safety state is taken

Manual Calibration:

Manual Calibration has to be done in config.h in the section related to the variant you have selected.
Make sure you are updating the primary input. Auxiliary inputs are for Dual input.

Setting the type of input:

  • If you don't need an input, disable it by setting INPUT1_TYPE or INPUT2_TYPE to 0, it will be ignored
  • For normal potis, set INPUT1_TYPE or INPUT2_TYPE to 1
  • For middle resting potis(e.g. Joystick), set INPUT1_TYPE or INPUT2_TYPE to 2
  • If INPUT1_TYPE or INPUT2_TYPE is set to 3, the right input type will be identified when you proceed with the auto-calibration

Setting Minimum, Middle and Maximum position:

  • Connect FTDI RX to blue wire from right sensor board cable to read USART DEBUG values, baud rate should be 115200 bauds (38400 bauds in older versions of the firmware)
  • Turn the potis to minimum position, write value 1: to INPUT1_MIN and value 2: to INPUT2_MIN in config.h
  • Turn the potis to maximum position, write value 1: to INPUT1_MAX and value 2: to INPUT2_MAX in config.h
  • For middle resting potis, let the potis in the middle resting position, write value 1: to INPUT1_MID and value 2: to INPUT2_MID

Config.h values will be ignored if you have already used the auto-calibration procedure below.

Deadband

DEADBAND parameter is used to set a dead area around the MIN or MID value that will still map to a zero input value.
For Normal pots:

  • Deadband>0----------> INPUT_MAX(1000)

For Mid-resting pots:

  • INPUT_MIN(-1000) <----------0< Deadband >0----------> INPUT_MAX(1000)

This is for example used with PWM or PPM variant to prevent jitters around 0 value due to signal noise.
This can get even worse in Speed mode as a smaller input will make the wheel turn compared to Voltage mode.
It can also help in addition to the auto-calibration if your joystick is not perfectly centered.

Auto-calibration:

Auto-calibration finds the minimum, middle and maximum values for the inputs. It also identifies the type of input and checks if it can be protected (ADC only).

How to enter auto-calibration mode

  • Turn the board on and press the power button for more than 5 sec and release after the beep sound
  • Move the potis freely to the min and max limits repeatedly
  • Release potis to the resting position
  • Press the power button to confirm or wait for the 20 sec timeout

⚠ FOC firmware might not pick up the button press if the voltage is too low.

Input type identification

If you haven't moved one of the inputs, if it's floating or is grounded, it will be identified as inactive and ignored(type=0).
If min and mid values are close, the inputs will be identified as normal potis(type=1).
Otherwise the inputs will be identified as middle resting potis(type=2).

For inputs with type 3 (AUTO) in config.h, auto-calibration will automatically identify the right input type. If input type 0,1,2 has been selected in config.h, auto-calibration will fail if identified input type is not matching and disable the input.

🖥️ Debug output

If you use Debug Serial, you can see the results of auto-calibration procedure:

Input calibration started...
Input1 is ignored..OK
Input2 is a normal pot AND protected..OK
Limits Input1: TYP:0 MIN:1158 MID:1059 MAX:973
Limits Input2: TYP:1 MIN:1115 MID:1015 MAX:2633
-- Motors enabled --

In this example:

  • Input1 was ignored as it was not connected or wasn't moved
  • Input2 was identified as a normal pot (pedal or throttle handle), and the minimum value is high enough to detect a floating input pulled to ground. If firmware reads a value below 915 ( MIN - ADC_PROTECT_THRESH ) for ADC_PROTECT_TIMEOUT time, it will trigger an ADC Timeout error.

💾 Saving the calibration

The limits will be saved/overwritten in flash memory when you turn the board off by pressing the button.

⚠The input limits (and maximum current and speed settings) will be persisted in flash memory even if you flash the firmware again, the only way to delete it is to fully erase the chip in st-utility before flashing.
An alternative to bypass those limits is to change FLASH_WRITE_KEY in config.h.

❌ Disabling the auto-calibration

If you have no use of auto-calibration feature and want to turn it off not to accidentally start this mode, you can disable it in config.h by commenting parameter AUTO_CALIBRATION_ENA. Firmware will still use previously saved auto-calibration values.

Add a custom footer
Clone this wiki locally