Getting Started with T-STorM32: Difference between revisions

Latest revision as of 20:48, 20 January 2024

The information on this page refers to firmware v2.37e and higher.

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 protection mechanisms to detect this and prevent this from happening, and experience shows that this works well, but there is no guarantee it handles all edge cases. Therefore, during the setup process, be prepared to intercept the gimbal by hands at startup to prevent a wrap up. Also - if possible - don't start with using your most expensive gimbal and camera.

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, NT Motor-Encoder modules, and a camera NT IMU module. Configurations, where e.g. the motors or the encoders are directly connected to the main STorM32 controller board, are not supported (if you want to know why, this picture here shows one of the several reasons).

From the perspective of the STorM32 controller, a motor and its associated NT Motor-Encoder module is regarded as one combined unit, and the STorM32 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 the settings in the STorM32 controller board are made.

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

GUI

The firmware allows us to run the encoder T-STorM32 and the conventional STorM32 versions intermittently, by simply setting a flag via the GUI's [GUI:Change Encoder Support Tool], without the need of any modifications to the hardware. This allows us to e.g. compare and evaluate performance differences in the two modes. It however implies that the firmware needs to be switched to T-STorM32 mode, before T-STorM32 can be used. The GUI detects the mode and adapts itself accordingly; the active mode can always be inferred from the GUI's window title.

Comment: The available parameters and options in the GUI are different in the encoder T-STorM32 and the conventional STorM32 mode. Thus, before using the GUI ensure that the STorM32 controller has been put into the desired mode, see Switching to T-STorM32 Mode.

Dont's

The T-STorM32 concept brings the battery power line and the control lines for the 3.3 V electronics in close proximity. For instance, the NT-X plugs carry both of them. This bears some risks, since the 3.3 V electronics will almost certainly be destroyed when it comes into contact with the battery voltage. For setup it is thus strongly recommended to be most careful and follow procedures which minimize the risks. For example: Do everything, which is possible to do without a connected battery, without a battery; when the battery shall be connected the first time or after a modification, connect it first to the STorM32 board with all NT modules disconnected; connect the NT modules one by one; don't connect/disconnect NT modules when a battery is connected. And so on.

WARNING: Please double and triple check the wiring, especially of the battery power line, before connecting the battery. Any mistake here will almost certainly kill some electronics and may even result in a loss of all electronics with one strike.

Ordering Information

Things to have at minimum:

STorM32 controller board
NT IMU module and matching cable
NT Motor-Encoder modules for each axis, with on-board or external encoders, and matching cables
USB-to-TTL adapter (only v1.x STorM32 boards)

Why the STorM32 board, the NT IMU module, and the NT Motor-Encoder modules are needed should be obvious from the T-STorM32's concept discussed before.

The USB-TTL adapter is required for flashing/upgrading v1.x STorM32 main boards to the latest firmware; it is not required for v3.x or v4.x STorM32 boards. Note though that a USB-TTL adapter allows one to use the Live Recording feature, which can be very helpful. So, it's a nice-have anyways.

Supported Gimbals

T-STorM32 supports the following setups:

3-axis with camera IMU: One NT IMU module, mounted to the camera, and three NT Motor-Encoder modules.
2-axis with camera IMU: One NT IMU module, mounted to the camera, and two NT Motor-Encoder modules.
1-axis with camera IMU: One NT IMU module, mounted to the camera, and one NT Motor-Encoder module.

T-STorM32 allows us to connect a 2nd IMU (IMU2) module. Its data are read, but are not used in any way by the STorM32 controller when in T-STorM32 mode, i.e., a 2nd IMU module 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. A 3rd IMU (IMU3) module can also be connected, it does not harm, but it is ignored completely, i.e., not even its data are read.

Encoders

T-STorM32 currently supports four types of encoders.

TLE5012B: The magnetic rotary encoder TLE5012B (any variant works, not only the E1000 variant) is the STorM32 standard encoder, and is e.g. used in all "OlliW" NT Motor-Encoder modules. This is also the normal way of using them, i.e., by getting one of the "OlliW" NT Motor-Encoder modules.

AS5048A: The magnetic rotary encoder AS5048A (it must be the A variant) is often offered together with commercial gimbal motors. It typically comes on a separate module with a number of solder pads, which allows one to operate it in PWM or SPI mode. T-STorM32 only supports the SPI mode, and using these encoders usually means that one has to solder wires to connect the AS5048A encoder module with the NT Motor module (which needs good soldering skills).

MA732: The magnetic rotary encoder MA732 excells by its tiny size, and is thus the go-to enoder for the smallest designs.

Resistive Encoders (Potentiometers): Potentiometers are the cheapest and in some way simplest means to measure the motor angle, but also have some significant disadvantages, such as low resolution, additional substantial friction, slope, hysteresis, limited angle range, and so on. They are thus not recommended and should be considered only in special cases.

The magnetic rotary encoders require in addition a magnet mounted properly to the gimbal motor. The typical choice would be a diametrically magnetized ring magnet (as opposed to the more common radially magnetized ring magnets, which cannot be used). For typical mounting configurations see What is T-STorM32 about: Concept.

Setting the IDs

Each NT module on the NT bus needs a unique ID to be properly recognized. Connecting two or more NT modules with identical ID to the NT bus will make it to not work. 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 complete 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 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, but it's recommended to do it via the solder pads. For details on this method see NT Module CLI.

Comment: The ID of the motor module also determines the LED blink pattern in normal operation: pitch: 1 blink per second, roll: 2 blinks per second, yaw: 3 blinks per second. This allows quick visual identification of the module's ID.

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

type of encoder
number of motor pole pairs
offset between mechanical and electrical angle

Depending on the encoder type there might be further parameters which needs to be set. 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 (e.g. disassembled and reassembled). For DIY builds one also first needs to check if the magnet and encoder are located properly, i.e., if the distance between them results in appropriate signal strengths and if 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.

The configuration of the NT Motor modules is done by accessing the CLI of the NT Motor module, either by using the [GUI:NT Module CLI Tool] located in the [GUI:Tools] menu, or by 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 normally 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. If possible the ex-situ method should be preferred.

Comment: The GUI's [GUI:NT Module CLI Tool] has been reported to work quite well now. It makes things more convenient, and you may prefer to use it instead of a terminal.

In-Situ Configuration

In this procedure the motor is moved 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 minor effects.

Important: In the course of the procedure you will have to connect a battery, but initially the battery should not be connected.

These are the steps:

Open the [GUI:NT Module CLI Tool], or start the terminal and connect with the STorM32 board (in both cases the correct COM port must have been selected). Ensure that no battery is connected (only USB connection).
Open tunnel: Open the tunnel to the NT module you want to talk to. [GUI:NT Module CLI Tool]: Hit the respective button. Terminal: Send "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 will now go into the 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 output screen of the [GUI:NT Module CLI Tool] or terminal you should see a welcome line such as "Hello, I'm MOTORPITCH", and the indicator ">".
Check encoder type: Run the command "getsetup;". Please do not forget the semicolon ";". All CLI commands should be finished with a semicolon. In the output screen 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;", "setmodelma732;", or "setmodelpotadc5;" depending on your encoder. Activate the setting by running the commands "store;" and "RESTART;". You should see again the welcome line appearing.
Connect battery: Connect a battery to the STorM32 board, in order to fully power the NT Motor module.
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.
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.
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 output screen. 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 additional "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;".
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;".
Disconnect battery: Disconnect the battery from the STorM32 board.
Close tunnel: Finish the tunnel mode. [GUI:NT Module CLI Tool]: hit the respective button. Terminal: 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 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 rotate freely. It should not be installed in the gimbal.

These are the steps:

Open the [GUI:NT Module CLI Tool], or start the terminal and connect with the STorM32 board (in both cases the correct COM port must have been selected). Power up the NT Motor module by connecting a battery.
Open tunnel: Open the tunnel to the NT module you want to talk to. [GUI:NT Module CLI Tool]: Hit the respective button. Terminal: Send "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 will now go into the 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 output screen of the [GUI:NT Module CLI Tool] or terminal you should see a welcome line such as "Hello, I'm MOTORPITCH", and the indicator ">".
Check encoder type: Run the command "getsetup;". Please do not forget the semicolon ";". All CLI commands should be finished with a semicolon. In the output screen 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;", "setmodelma732;" or "setmodelpotadc5;" depending on your encoder. Activate the setting by running the commands "store;" and "RESTART;". You should see again the welcome line appearing.
Check encoder distance: Run the command "rrange;". The motor should start to turn, and in the output screen values should be displayed. The displayed values depend on the type of the used encoder chip. For a TLE5012B encoder the adcx and adcy values should be in the range of +/- 6000 ... 15000. For a AS5048A encoder the mag values should be around 4000. No errors should have occurred.
Determine number of motor pole pairs: Run the command "rpp;". The motor makes one turn. The result is displayed in the output screen.
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 pole pairs and the offset are stored permanently in the NT module. You can double check by running "getsetup;".
Close tunnel: Finish the tunnel mode. [GUI:NT Module CLI Tool]: Hit the respective button. Terminal: 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.

Tstorm32-gui-motorencodermoduleconfiguration-as5048a-wclitool.jpg

Basic Controller Configuration

With all 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.

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.

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.

Quick Trouble Shooting:

"ERROR: EMERGENCY shut down!": The emergency shutdown occurs when a very fast motor movement for a "too long" period of time is detected. The motors are then shut down to protect your gimbal. This error always indicates that something is miserably wrong with the setup and/or configuration, so you need to go carefully through it again. The prototypical reason for this to occur is that some "signs" are not correct, which make the motor to move in the wrong direction. But it can also be caused by unreliable wiring, or massively wrong PID values.

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 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):

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

Getting Started with T-STorM32: Difference between revisions

Latest revision as of 20:48, 20 January 2024

Contents