Getting Started with T-STorM32
descriptions refer to firmware v2.26a and later
This is a first attempt of a documentation for the T-STorM32, the encoder version of the STorM32 gimbal controller.
DISCLAIMER: The encoders bring many advantages, but also one disadvantage: The motors are now effectively speed-controlled, which means that when something goes "wrong" the gimbal or camera can quickly wrap up itself, resulting in possible damage. The current firmware has some protection mechanisms to prevent this from happening. However, I may have missed the edge case relevant to you. In short: Don't start with using your most precious gimbal and camera. Also, be prepared to intercept the gimbal by hands at startup. I shall not be held responsible.
Opening Remarks
The T-STorM32's concept for the encoder support is discussed in What is T-STorM32 about?. It consists of a main STorM32 controller board, three NT Motor-Encoder modules, and a camera NT IMU module. Other configurations, where e.g. the motors or the encoders are connected to the main STorM32 controller board, are not supported.
From the perspective of the main controller, the NT Motor-Encoder module and the motor associated to one axis is regarded as one combined unit. This implies a two-step configuration procedure: First the "NT Motor-Encoder module + motor" unit is configured, and then the firmware in the main controller board.
Comment: In the following the NT Motor-Encoder modules are also denoted as "NT Motor modules" for brevity.
Ordering Information
Things to have at minimum:
- STorM32-BGC board
- NT IMU module and matching cable
- three NT Motor-Encoder modules, with on-board or external encoders, and matching cables
- USB-to-serial adapter
The need for the STorM32 board, the NT IMU module, and the three NT Motor-Encoder modules should be obvious from the T-STorM32's concept discussed before. The USB-to-serial adapter is required for upgrading v1.x STorM32 main boards to the latest firmware (not required for v3.x STorM32 boards). It can also be used for the Live Recording feature, which can be very helpful.
Supported Gimbals
T-STorM32 currently supports the following setups:
- 3-axis with camera IMU: One NT IMU, mounted to the camera, and three NT Motor-Encoder modules.
The T-STorM32 allows connecting a 2nd IMU (IMU2). However, its data are read but not used at all. It's there only to help e.g. with vibration analyses. Connecting a 3rd IMU (IMU3) doesn't harm, but it is ignored completely, i.e. its data are not even read.
NT Motor-Encoder Module Configuration
As mentioned before the combination of a NT Motor module with its motor is treated as one unit. This makes sense logically, and has its advantages (it also has its disadvantages).
The first step in the gimbal configuration consists of configuring the NT Motor modules, for each axis. Two parameters need to be set, namely the number of motor poles, and the offset between mechanical and electrical angle. These values are stored permanently in the NT Motor module, and need never be modified once set, unless of course the "NT Motor module + motor" unit is modified. For DIY builds one also needs to check beforehand that the magnet and encoder are located properly, i.e., that the distance between them results in appropriate signal strengths and that they are properly centered. In addition, the NT Motor module firmware includes options to run various test sequences, which provide detailed information on the motor properties and can yield much insight into its performance.
Important: In the following configuration steps, the motor should be unloaded. In particular, it must not be installed in the gimbal.
Currently, the configuration of the NT Motor modules is not possible via the GUI, but requires accessing the CLI of the NT Motor module using a standard terminal program, such as HTerm. The typical approach is this: Connect the NT Motor module to the STorM32 main board via the NT bus, and the STorM32 main board to the PC, exactly as one would do for normal operation. For accessing the CLI of the NT Motor module, the STorM32 main board has first to be put into a pass-through mode by sending a special command to it. It then works as tunnel connecting the PC with the selected NT Motor module.
This are the steps:
- Start the terminal and connect it to the STorM32 board. Power up the NT Motor module by connecting a battery.
- Open tunnel: Open the tunnel to the NT module you want to talk to by sending "xQTcNTQMODE" plus the ID of the NT module as a double-digit: To talk to the pitch NT Motor module with ID = 4, you send "xQTcNTQMODE04" (without the quotation marks), for roll you add 05, and for yaw 06. The STorM32 board goes into tunnel mode, which can be recognized on the STorM32 board by a dark green LED and fast-blinking red LED, and the addressed NT module starts its CLI. On the terminal you should see a welcome line such as "Hello, I'm MOTORPITCH", and the indicator ">".
- Check encoder distance: Run the command "rrange;". Please do not forget the semicolon ";". All CLI commands should be finished with a semicolon. The motor should start to turn, and in the terminal values should be displayed. The adcx and adcy values should be in the range of +/- 6000 ... 15000, and no errors should have occurred. The displayed values depend on the type of the used encoder chip.
- Determine number of motor pole pairs: Run the command "rpp;". The motor makes one turn. The result is displayed in the terminal. The number can be positive or negative, which accounts for the motor spin direction, which in turn depends on how the motor phases are connected to the NT Motor module. Note that the number of pole pairs is determined, i.e., for a 14 pole motor it is +/- 7.
- Determine offset: Run the command "rofs;". The motor makes about 4 turns in one direction and 4 turns in the opposite direction. The result is displayed. The number of motor poles must have been set correctly before for this command to work correctly.
- Store results: Run the command "store;". The determined number of motor poles and the offset are stored permanently in the NT module. You can double check by running "getsetup;".
- Close tunnel: To finish the tunnel mode run the command "@Q". This brings both the NT module and the STorM32 main board back to normal operation. This takes few seconds.
With these steps the "NT Motor module + motor" unit is fully operational and ready to go. It can now be installed in the gimbal.
Basic Controller Configuration
With all three NT Motor modules configured, and the gimbal fully assembled, the basic configuration can be completed. The final steps can be conveniently done using the GUI.
The main controller board should be connected via its USB port to the PC, but disconnected from the battery.
Switching to T-STorM32 Mode
At first, the main controller and GUI have to be put into encoder or T-STorM32 mode. The firmware allows us to run the conventional STorM32 and the encoder T-STorM32 versions intermittently, by setting an option in the GUI, without the need of any modifications to the hardware. This allows us to, e.g., compare and evaluate performance differences.
Ensure that the motors are disabled (don't forget to Write+Store) if that is the first time you switch to the T-STorM32 mode.
For switching to the T-STorM32 mode, connect the main controller to the GUI, and open the [Change Encoder Support Tool]. Select "on" and hit the [OK] button, as shown in the figure. This will reconfigure the main controller firmware and the GUI. The active mode can always be inferred from the GUI's window title.
In the GUI, some parameters will disappear, some parameters be disabled, and some new parameters appear. The new parameters, which are specific to the T-STorM32 mode, have a preceding "Foc" in their names.
Comment: It may happen that at some point in the future the STorM32 and T-STorM32 firmwares branch off. However, the current dual-mode option will be kept for as long as possible.
Setting Configuration Parameters
Three types of parameters need to be determined, the orientation of the camera IMU (IMU1), the zero position of the encoders for each axis, and the motor spin direction for each axis. The corresponding parameter fields are located on the [GUI:Gimbal Configuration] tab, see the figure.
1. Camera IMU Orientation
Setting the camera IMU orientation is done exactly as for the conventional STorM32, most easily by running the [GUI:Configure Gimbal Tool]. Please consult the STorM32 wiki for further information.
Comment: It is recommended to restart the gimbal before proceeding to the next step, in order to ensure that the AHRS for the camera IMU has settled to the new IMU orientation.
2. Encoder Zero Positions
Put your gimbal into a perfectly square position, i.e., orient it such that all gimbal axes have a 90° angle, and that the camera points forward with respect to the gimbal. Ideally this would be realized by leveling both the gimbal base and the camera holder with bubbles, as this would yield the most accurate result. However, some tolerance is allowed.
With the gimbal oriented that way, go to the [GUI:Tools] menu and run [Get Current Encoder Positions], as indicated in the figure. This writes the current encoder angles into the parameter fields Foc Pitch Zero Pos, Foc Roll Zero Pos, and Foc Yaw Zero Pos, and completes this configuration step.
3. Motor Directions
The procedure of setting the motor direction is described for the pitch axis exemplarily.
Start the [GUI:Data Display], and in the middle plot check the check boxes for the IMU1 and encoder pitch angles. Uncheck them for the roll and yaw axes. With the gimbal and camera in the default position, the two lines in the plot should be close to each other. Now tilt the camera up and down by hand (only camera, not the gimbal base). The two lines in the plot should continue to follow each other. If they deviate in opposite directions, then the motor direction for the pitch axis needs to be reverted.
Repeat the process for the roll and yaw axes.
4. Store Configuration Parameters
Do not forget to store the parameters, in order to keep them permanently.
First Startup
After the above steps have been completed, the gimbal can be started up (please note the warning below!).
At startup, the controller goes through some initialization steps, which typically take just a few seconds. Note that the gimbal should not be moved until the initialization is finished, and the controller has reached normal operation. This is indicated by the green LED going solid, and - if enabled - by a beep.
Initialization Steps: SETTLE - CALIBRATE - FASTLEVEL - NORMAL
- SETTLE: In order to calibrate, the gimbal has to be stable, it should not be moved. For a copter this is simple as the copter is on the ground. A handheld device needs to be put to rest for a few seconds.
- CALIBRATE: Calibrates the sensors. Takes a second or so.
- FASTLEVEL: The controller moves the camera into level position.
- NORMAL: This is the final stage; the gimbal is fully operational. Whatever you do, the camera should remain now stable.
Led Signals: The progress of the initialization is also indicated by the green LED on the board: During initialization it flashes with varying frequency. When initialization has finished and NORMAL state been reached, it goes solid. If beeps are activated, then the motors will emit a sound. The current state of the controller can also be seen in the status line of the GUI, or the Data Display. The red LED always blinks with a frequency of 1 Hz, except in certain fault conditions or special states, in which case it blinks very fast.
Operational Range: You can pitch and yaw the camera indefinitely. The roll angle is limited to +-80° or so. Larger roll angles are not possible since then the pitch and yaw axes become aligned, leading to gimbal lock.
WARNING: At this point in the configuration process the PID values have not yet been tuned, which would be the next step. That means that the gimbal can start to undergo wild shakes, which can harm your camera and/or gimbal.
This procedure is suggested: Disable both the roll and yaw motor before the first power up, and have only the pitch motor enabled. Power up the gimbal, but be prepared to intercept the gimbal at any time with your hands in case of too violent shakes. Tune the pitch axis to the extend that it doesn't freak out. Repeat for the roll, and then the yaw axis.
Basic Tuning
Before we proceed, this reminder: The gimbal needs to be balanced. Please read and adhere to Balancing the Gimbal.
Generally, tuning is easier for the T-STorM32 than for the conventional STorM32. This is because the unit consisting of the NT Motor-Encoder module plus motor pretty much behaves like an ordinary DC motor, or a speed-controlled first-order system, in contrast to the situation with the conventional STorM32. That is, it behaves exactly like the standard situation considered for PID tuning. As a byproduct, all the common knowledge on PID tuning does directly apply.
The relevant parameters are located on the [GUI:PID] tab.
For a basic tuning, this procedure can be suggested (the pitch axis is considered exemplarily):
- Set Foc Pitch K to “1.0”.
- Set Foc Pitch I to a small value, for instance to “10.0”.
- Increase Foc Pitch D until the gimbal starts oscillating, or the upper limit is reached.
- Increase Foc Pitch P until the gimbal stops oscillating, or the upper limit is reached.
- Repeat the last two steps until a sort of a maximum is achieved, i.e., until increasing either P and D does not stop the vibrations. If it happens that the available range for one of the two parameters is exhausted, increase the value of K by a small amount, maybe by 0.5 or so, and reduce both P and D.
- Lower both P and D somewhat, by maybe 15% or so.
- Increase Foc Pitch I. You will find that the exact value does not matter a lot. So, set it to a high value but at the same time be conservative.
This should result in a basic tuning, that is, in a reasonable but maybe not yet optimal performance.
Comment: It often can be helpful to try different values for Foc Gyro LPF.
Next Step
The gimbal is now fully operational, and should perform reasonably well.
For optimal performance you may have to spend some more time on fine-tuning the gimbal, especially in handheld applications where large angle ranges shall be covered. However, that's not different from what you're used to from the conventional STorM32 controller.
From here on, you may follow the tutorials for the conventional STorM32, e.g. continue with Configure the RC Input.