docs/configuration-pan-servo.md

   1 # Pan Servo Configuration
   2
   3 It's time to connect the servos and the serial adapter through which telemetry will be received, for example, the Bluetooth module.
   4
   5 Connect the battery to the tracker, initiating the startup sequence.
   6
   7 If you configured the init_servos parameter to a value of 1, the tracker will rotate for no more than a second, and not very fast. It should stop just when the blue LED becomes steady, indicating that the startup sequence has completed.
   8
   9 If you configured the **init_servos** parameter to a value of 0, none of the servos should move during the startup sequence.
  10
  11 In any case, if the tracker continues to rotate after the startup sequence, it should not do so very quickly, as we have set the pan0 parameter with a value of 1500 as the stop pulse. You may need to adjust this value.
  12
  13 The adjustment of the PAN0 value can be done in two different ways:
  14
  15 - Manually
  16 - Automatically (starting from version 6.6.x or higher).
  17
  18 ## Parameters
  19
  20 Here are the configuration parameters that allow you to customize the pan servo's operation:
  21
  22 - **init_servos**
  23    - **Type:** Integer
  24    - **Valid Range:** 0 or 1
  25    - **Description:** This parameter controls the behavior of the servos during the tracker's startup sequence. If set to 1, the tracker will rotate for a brief period, no longer than a second, at a moderate speed. It will automatically stop when the blue LED remains steadily on, indicating that the startup sequence has completed. If set to 0, none of the servos should move during the startup sequence. It's essential to note that if the tracker continues to rotate after the startup sequence, it should not do so at a high speed. This is because the `pan0` parameter has been configured with a value of 1500 as the stop pulse, and this value may require adjustment.
  26
  27 - **calibration_pulse**
  28    - **Type:** Integer
  29    - **Valid Range:** Customizable
  30    - **Description:** The calibration pulse represents the signal sent to move the pan servo during calibration. By default, it is set to 1400, but it may need adjustment based on your hardware's central stop pulse.
  31
  32 - **pan0**
  33    - **Type:** Integer
  34    - **Valid Range:** Customizable
  35    - **Description:** The central stop pulse (Pan0) is calculated as the midpoint between the lower and upper limits of the stop pulse range (min_pan0 and max_pan0).
  36
  37 - **min_pan_speed**
  38    - **Type:** Integer
  39    - **Valid Range:** Customizable
  40    - **Description:** Min Pan Speed is calculated as half of the difference between max_pan0 and pan0. It determines the minimum speed at which the servo starts moving.
  41
  42
  43 ## Automatic Pan Servo Calibration
  44
  45 For automatic pan servo calibration process, the magnetometer sensor is required, and also a value for calibration pulse, which should be lower than the spected stop pulse. By default calibration pulse is 1400 because we spect a value arround 1500 for the central stop pulse. If you suspect that you have a central stop pulse different than the default one, you may change it to a more properly value. If your servo has a high dynamic range, then try set the calibration pulse not too far away from the suspected central stop pulse, in this way your servo will spin slower but during less time than with a  further calibration pulse value (passing through the whole dynamic range is not needed for this calibration process).
  46
  47 In some cases interference on the magnetometer may lead to a long time being required to detect that the servo has stopped, due to the precision used to detect it. If this is the case, try calibration away from external electromagnetic fields. Also try to place the magnetometer as far away as possible from metal objects, such as screws, servos, ..., and especially power cables.
  48
  49 If the process take too much time and you want to interrupt, you need to cut power and click on disconnect button.
  50
  51 ### First step, mag calibration:
  52
  53 The controller sends the calibration pulse to the servo, which starts spinning counter clock wise. Durig 10 seconds the controller retrieves data from the sensor, and calculates magzero x, y and z values. Then the controller sends the stop pulse to the servo, and if its value has been properly configured previously, it stops spinning. However, if the stop pulse was no properly configured previously, the tracker continues spinning. In both cases, after 10 seconds, the mag calibration process has finished, and the controller jumps to second step.
  54
  55 **Note:** When calibration pulse is lower than central stop pulse, the tracker spins **counter clock wise** for the calibration process. And when calibration pulse is greater than stop pulse, the tracker spins clock wise. **If the tracker does not spin as described during compass calibration process**, then your **pan servop is reversed**. You may solve it executing these commands from CLI:
  56
  57 ```
  58 set pan_inverted=on
  59 save
  60 ```
  61
  62 Alternatively you may do a hardware mod which consist on inverting the polarity of the wires directly connected to the motor (do the mod under your own risk).**
  63
  64 ### Second step, central stop pulse (pan0) calibration:
  65
  66 The controller sends again the calibration pulse, and the tracker starts or continues spinning, depending on previous step. In each algorithm cycle the value of the pulse is decreased, and as the value gets closer to the central stop pulse servo speed decreases.
  67
  68 At the same time the controller retrieves heading angles values and calculates how small the difference between consecutive values is. When this difference is equal or less than a specific threshold (0.2 degrees) the controller assumes that it has stopped spinning, and stores the last sent pulse as the lower value within a range of stop pulses. Now, the controller waits 3 seconds, and measure again heading value. If a difference greater than 5 degrees is detected then the controller assumes that the tracker is still in movement, and sends again the calibration pulse. The process is repeated as necessary until the lower stop pulse value is calculated (e.g. min_pan0 = 1511 usec)
  69
  70 Once the lower value for the stop pulse range has been calculated, the controller sends a calibration pulse higher than the spected central stop pulse. The valuee of the new calibration pulse is calculated as follows:
  71
  72 **calibration pulse = central stop pulse + (central stop pulse - calibration pulse) = 1500 + (1500 - 1400) = 1600 usec**
  73
  74 This time the tracker starts spinning clock wise. Again, as the value gets closer to the central stop pulse servo speed decreases. If the controller detects that the servo has stoped (heading difference of 0.2 degrees), it stores the last sent pulse as the higher value for the range of stop pulses. If after 3 secods a movement is detected (headding difference greater than 5 degrees) the controller sends again calibration pulse. The process is repeated as necessary until the higher stop pulse value is calculated (e.g. max_pan0 = 1527 usec).
  75
  76 Now that we have the value of both limits of the range, the central stop pulse (pan0) is calculated as follows:
  77
  78 **pan0 = min_pan 0 + (max_pan0 - min_pan0) / 2 = 1511 + (1527 - 1511) / 2 = 1511 + 8 = 1519 usec**
  79
  80 During the process values for central stop pulse are automatically updated several times, and entries are shown on log panel.
  81
  82 ### Third step, minimun increment of speed to start movement (min_pan_speed):
  83
  84 Now the algorithm calculates the value of min_pan_speed parameter as follows:
  85
  86 **min_pan_speed = (1527 - 1511) / 2 = 8 usec**
  87
  88 and the configurator updates its value.
  89
  90 ### Final step
  91
  92 Finally the tracker has sttoped spinning, and some beeps confirms that the automatic pan servo calibration process has finished.
  93
  94 ## Manual Pan Servo Calibration
  95
  96 Calibration pulse is not an stop pulse (min or max), it is only a pulse we need to start movement for the calibration, it has nothing to do with calculations. If you think that the pan0 (stop pulse) value might be arround 1500, we set calibration pulse as 1400. This calibration pulse is used only during automatic calibration proccess.
  97
  98 During automatic calibration, the tracker will try to figure out the min_pan0 pulse (pulse lower than pan0 where the tracker stops) and max_pulse (pulse higher than pan0 where the tracker stops). This is because the servo stops movement whithing a range of pulses.
  99
 100 For a better precission you may caluculate pan0 and min_pan_speed manualy. You should figure out the min_pan0 and max_pan0 pulses using the up/down arrows of stop pulse field of the GUI, and then do the calculations bellow.
 101
 102 e.g.:
 103
 104         min_pan0 = 1495
 105         max_pan0 = 1530
 106
 107 Lets calculate the stop pulse:
 108
 109         pan0 = min_pan 0 + (max_pan0 - min_pan0) / 2
 110
 111         pan0 = 1495 + (1530 - 1495) / 2 = 1512.5
 112
 113         Rounded pan0 = 1513
 114
 115 And finally the minimun increment to start moving:
 116
 117         min_pan_speed = (max_pan0 - pan0) / 2
 118
 119         min_pan_speed = (1530 - 1513) / 2 = 8.5
 120
 121         Rounded min_pan_speed = 9
 122
 123 [<< Go back](README.md)