Getting Started with T-STorM32

descriptions refer to firmware v2.37e and later

This is the 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 acquire speed and quickly wrap up itself, resulting in possible damage. The firmware has some protection mechanisms to detect this and prevent this from happening. However, not all edge cases might be handled yet. Therefore, during the setup process: Be prepared to intercept the gimbal by hands at startup. Also, if possible, don't start with using your most precious gimbal and camera. In any case, I shall not be held responsible.

Opening Remarks

The T-STorM32's concept for the encoder support is discussed in the article 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 (if you want to know why, here is one of the several reasons).

From the perspective of the main controller, a motor and its associated NT motor-encoder module is regarded as one combined unit, and the main controller doesn't need to know about this unit's internals. This results in a two-step configuration procedure: First the "NT motor-encoder module + motor" unit is configured, and then in a second step settings in the firmware in the STorM32 controller board.

Comment: In the following the NT motor-encoder modules are also denoted as "NT motor modules" for brevity.

The firmware allows us to run the encoder T-STorM32 and the conventional STorM32 versions intermittently, by setting a flag in the GUI, without the need of any modifications to the hardware. This allows us to, e.g., compare and evaluate performance differences. This however implies that the firmware and GUI need to be switched to the T-STorM32 mode before T-STorM32 can be used (see Switching to T-STorM32 Mode).

Comment: The available parameters and options in the GUI are different in the encoder T-STorM32 and the conventional STorM32 mode.

Ordering Information

Things to have at minimum:

• STorM32 controller board
• NT IMU module and matching cable
• three NT motor-encoder modules, with on-board or external encoders, and matching cables
• USB-to-TTL 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-TTL adapter is required for upgrading v1.x STorM32 main boards to the latest firmware; it is 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.

T-STorM32 allows connecting a 2nd IMU (IMU2). Its data are read, but are not used in any way by the STorM32 controller, i.e., a 2nd IMU is not required for operation. However, the 2nd IMU data are recorded by the NT logger, which can be of help in e.g. vibration analyses. Connecting a 3rd IMU (IMU3) doesn't harm, but it is ignored completely, i.e., not even its data are read.

Setting the IDs

Each NT module on the NT bus needs its unique ID to be properly recognized. Connecting two or more NT modules with identical ID to the NT bus will make it not working. Therefore, the ID of each NT module must be set beforehand.

The pitch, roll and yaw motors are assigned the IDs 4, 5, and 6, respectively. The full list of IDs is given here: NT Bus Protocol: Concept.

Most NT motor-encoder modules provide two solder pads for configuring the ID. Close the "R" pad with solder to configure for the roll axis, close the "Y" pad to configure for the yaw axis, and leave both pads open to configure for the pitch axis.

The ID can also be configured via the CLI of the NT motor-encoder module. For details see NT Motor&Encoder Module CLI.

NT Motor-Encoder Module Configuration

The first step in the gimbal configuration consists of configuring the NT motor modules, for each axis. Three parameters need to be set for each NT motor module, namely the type of the encoder, the number of motor pole pairs, and the offset between the 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 in some way. 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.

Comment: The number of pole pairs can be positive or negative. The sign 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 or -7.

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 normally would do it. The CLI of a NT motor module can be accessed by putting the STorM32 main board 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.

For the configuration, two procedures are available: The in-situ method can be done with the gimbal fully assembled, but is less accurate. In contrast, the ex-situ method requires that the motor can freely rotate, but is most accurate, and offers a number of test sequences to evaluate the performance of the motor.

In-Situ Configuration

---

This procedure works by moving the motor back and forth around a center position within a given angle range (per default +-45° on roll and +-60° on pitch and yaw). It thus can be run with the gimbal fully assembled (also the camera must be installed and the gimbal be balanced). However, it may fail to determine correctly the number of motor pole pairs in some cases, especially for coggy motors and poorly balanced gimbals. So, you should know the number of motor poles for your motors (the number of pole pairs is half of that number).

Comment: The motor direction or sign of the pole pairs number is determined correctly by the procedure, i.e., only the magnitude of the pole pairs may come out wrongly. The offset is also determined correctly, but less accurately as with the ex-situ method. This should however have only secondary effects.

Important: You will have to connect a battery, but initially the battery should not be connected.

These are the steps:

1. Start the terminal and connect with the STorM32 board. Ensure that no battery is connected (only USB connection).
2. 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 and the addressed NT module starts its CLI. This can be recognized on the STorM32 board by a dark green LED and fast-blinking red LED. In the terminal you should see a welcome line such as "Hello, I'm MOTORPITCH", and the indicator ">".
3. Check encoder type: Run the command "getsetup;". Please do not forget the semicolon ";". All CLI commands should be finished with a semicolon. In the terminal you should see the current setup values. Check that the entry for 'EncoderModel' matches the used encoder. If it does not match, then run the command "setmodeltle5012b;", "setmodelas5048a;" or "setmodelpotadc5;" depending on your encoder. Activate the setting by running the commands "store;" and "RESTART;". You should see again the welcome line appearing.
4. Connect battery: Connect a battery to the STorM32 board, in order to fully power the NT motor module.
5. Check encoder: This is optional. Run the command "reval;". You may now turn the motor by hand and watch the values printed in the terminal to check for correct operation. The displayed values depend on the type of the used encoder chip. Terminate the command by sending any character to the NT module.
6. Center the motor: Run the command "moveby 50;" or "moveby -50;" repeatedly, until the motor is roughly centered, i.e., the camera is in its normal position within few degrees.
7. Determine number of motor pole pairs and offset: Run the command "r2ppofs;". The motor will sweep back and forth a couple of times. The result is displayed in the terminal. The determination of the number of pole pairs is not totally reliable and may fail (the sign is ok, the magnitude may be wrong). In that case run the command "r2sppofs X;" where X is the known number of pole pairs (i.e. run "r2sppofs 7;" for a 14 pole motor)(note the "s" in the command). The procedure will then set only the sign of the pole pairs value, not its magnitude. It also will determine the offset, as with "r2ppofs;".
8. Store results: Run the command "store;". The determined number of motor pole pairs and the offset are stored permanently in the NT module. You can double check by running "getsetup;".
9. Disconnect battery: Disconnect the battery from the STorM32 board.
10. 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.
11. With these steps the "NT motor module + motor" unit for the chosen axis is fully operational and ready to go. Repeat for all axes.

Ex-Situ Configuration

---

Important: In the following configuration steps, the motor should be unloaded and must be able to freely rotate. It should not be installed in the gimbal.

These are the steps:

1. Start the terminal and connect with the STorM32 board. Power up the NT motor module by connecting a battery.
2. 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 and the addressed NT module starts its CLI. This can be recognized on the STorM32 board by a dark green LED and fast-blinking red LED. In the terminal you should see a welcome line such as "Hello, I'm MOTORPITCH", and the indicator ">".
3. Check encoder type: Run the command "getsetup;". Please do not forget the semicolon ";". All CLI commands should be finished with a semicolon. In the terminal you should see the current setup values. Check that the entry for 'EncoderModel' matches the used encoder. If it does not match, then run the command "setmodeltle5012b;", "setmodelas5048a;" or "setmodelpotadc5;" depending on your encoder. Activate the setting by running the commands "store;" and "RESTART;". You should see again the welcome line appearing.
4. Check encoder distance: Run the command "rrange;". 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.
5. Determine number of motor pole pairs: Run the command "rpp;". The motor makes one turn. The result is displayed in the terminal.
6. 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.
7. Store results: Run the command "store;". The determined number of motor pole pairs and the offset are stored permanently in the NT module. You can double check by running "getsetup;".
8. 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.
9. 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 as described in the previous section, and the gimbal fully assembled (and the camera installed and the gimbal balanced), the basic configuration can be completed. The final steps can be conveniently done using the GUI.

The STorM32 controller board should be connected via its USB port to the PC, but be disconnected from the battery.

Switching to T-STorM32 Mode

---

At first, the STorM32 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 no battery is connected or that the motors are disabled (don't forget to Write+Store) if this is the first time you switch to the T-STorM32 mode, i.e., if the gimbal is not set up completely.

For switching to the T-STorM32 mode, connect the STorM32 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 STorM32 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 will be disabled, and some new parameters will appear. The 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.

It is configured with the parameter Imu1 Orientation in the [GUI:Gimbal Configuration] tab. The correct orientation may be determined manually, following the article Manually Setting the IMU Orientation, or by using the [GUI:Configure Gimbal Tool]. The STorM32 controller should not be connected to a battery, only to USB.

The camera IMU should also be calibrated. Follow the descriptions in Calibration Procedure. A 1-point calibration is sufficient in nearly all cases.

Comment: The Configure Gimbal Tool must only be used for setting the Imu1 (and Imu2) orientation, it cannot be used otherwise for setting up a T-STorM32 gimbal. Only the Imu1 and Imu2 Orientation checkboxes, and the two last ones listed under Finish, may be used, all other checkboxes must be unchecked (when the GUI is in T-STorM32 mode these in fact should not be even displayed, that is, if you see them, then better double check what you're doing).

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.

WARNING: At this point in the configuration process the PID values have not yet been tuned, which would be the next step. The default PIDs should work for most gimbals, but if not, the gimbal can undergo wild shakes at startup when powered up. The STorM32's protection mechanism should detect this and shut off the motors, but it's recommended to be alert to prevent damage to the gimbal or camera. See recommendations given in the next chapter if that happens.

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 level now.

Led Signals: The progress of the initialization is also indicated by the green LED on the STorM32 controller 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° and >+-100° or so. The range of "dead angles" around +-90° is not possible since the pitch and yaw axes become aligned, leading to gimbal lock. Practically this means that the gimbal can be started up in both the up-standing or down-hanging configurations, independent on what was used in the setup procedure. Also, the gimbal can be "flipped over" during operation, when the range of dead angles around +-90° is passed quickly enough. This needs some practicing though, but works.

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.

As mentioned in the previous chapter: The default PID parameters might not work for your gimbal. This procedure is then 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.

The relevant parameters are located in the [GUI:PID] tab.

For a basic tuning, this procedure can be suggested (the pitch axis is considered exemplarily):

1. Set Foc Pitch K to “1.0”.
2. Set Foc Pitch I to a small value, for instance to “10.0”.
3. Increase Foc Pitch D until the gimbal starts oscillating, or the upper limit is reached.
4. Increase Foc Pitch P until the gimbal stops oscillating, or the upper limit is reached.
5. Repeat the last two steps until a sort of a maximum is achieved, i.e., until increasing either P or 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 accordingly.
6. Lower both P and D somewhat, by maybe 15% or so.
7. 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.