Getting Started with T-STorM32

From STorM32-BGC Wiki
Jump to navigation Jump to search

This is a first attempt of a documentation for the T-STorM32. Will be relatively disorganized at first.

Opening Remarks

The T-STorM32's concept for the encoder support you find discussed in What is T-STorM32 about?. It consists of a main controller board, three NT motor-encoder modules, and a camera NT IMU module.

From the perspective of the main controller, the NT motor-encoder module and 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 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 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. The USB-to-serial adapter is required for upgrading the STorM32 main board to the latest firmware. It is also needed for applying the Live Recording feature, which can be extremely useful.

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. not even its data are 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 of course 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: For 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 the use of a standard terminal program, such as HTerm. It can be done in two ways:

  • The NT motor module is connected to a STorM32 main board (via the NT bus), and the STorM32 main board is connected to a PC, either via the main board's USB port or the UART port. In that case the 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 module.
  • The NT motor module is connected on its NT port directly to a PC via a USB-TTL adapter, pretty much as one would do for Live Recording, except that now both the Tx and Rx lines need to be connected to the USB-TTL adapter.

In the following we will assume the first approach:

  1. Start the terminal and connect it to the STorM32 board. Power up the NT motor module with a battery.
  2. 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. For instance, to talk to the pitch motor module with ID = 4, you send "xQTcNTQMODE04" (without the quotation marks). The STorM32 board goes into tunnel mode, which can be recognized by a dark green LED and fast-blinking red LED, and the addressed NT module starts its qmode. On the terminal you should see a welcome line such as "Hello, I'm MOTORPITCH", and the indicator ">".
  3. Check encoder distance: Run the command "rrange;". The adcx and adcy values should be in the range of 6000 ... 15000, and no errors should have occurred.
  4. Determine the 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.
  5. Determine the 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.
  6. Store the results: Run the command "store;". The determined number of motor poles and offset are stored permanently in the NT module. You can double check by running "getsetup;".
  7. 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. The intention is to allow the users to compare and evaluate e.g. performance differences. At some point in future it may happen that the STorM32 and T-STorM32 firmwares branch off, but this dual-mode option will be kept as long as possible.

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.

Tstorm32-gui-switchtoencoders.jpg

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.

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.

Tstorm32-gui-basicconfiguration.jpg

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, 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 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.

Tstorm32-gui-getcurrentencoderpositions.jpg

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.

Comment: The current configuration process is easy, but somewhat clumsy. This may improve in future firmware versions.

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.

Tstorm32-gui-pids.jpg

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 “1.0”.
  3. Increase Foc Pitch P until the gimbal starts oscillating.
  4. Increase Foc Pitch D until the gimbal stops oscillating.
  5. Repeat these 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.
  6. Lower both P and D somewhat, by maybe 15% or so.
  7. Increase Foc Pitch I. You will not find the exact value to 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 should now be fully operational, and 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 Next Step - RC Inputs.